Connect tools

In your project, add a custom tool and point it at your endpoint. You give it a name, a plain description (the agent reads this to decide when to use it), a method and URL, and a JSON schema for its inputs. This is the full stored shape of a tool, with every default spelled out.

{
  "name": "lookup_order",
  "display_name": "Look up an order",
  "description": "Look up the status of a customer order by its id.",
  "enabled": true,
  "input_schema": {
    "type": "object",
    "properties": { "order_id": { "type": "string" } },
    "required": ["order_id"]
  },

  "executor_type": "webhook",
  "webhook_url": "https://api.acme.com/orders/lookup",
  "webhook_method": "POST",
  "webhook_headers": { "Authorization": "Bearer {{user.auth_token}}" },
  "webhook_params": { "tenant_id": "{{user.data.tenant_id}}" },

  "requires_confirmation": false,
  "collection_triggers": []
}

A mock tool is a prototyping aid. It makes no outbound request. It echoes the parameters declared in input_schema merged with whatever the model sent, adds a slice of the caller's profile, and marks the payload "mock": true. The values are invented, and the agent will present them to the user as if they were real.

{
  "success": true,
  "mock": true,
  "result": "Mock response from 'lookup_order' — connect a webhook for real data.",
  "params": { "order_id": "A-40912" },
  "user": { "id": "u_42", "name": "Alice Chen", "role": "admin" }
}

For every method except GET, Agentifys sends a JSON body with three top-level keys: tool, input, and user. The model's arguments are nested under input, not spread at the top level, so read body.input.order_id, not body.order_id.

// POST https://api.acme.com/orders/lookup
// Content-Type: application/json
// Idempotency-Key: 7f3a91c2:toolu_01H8
// Authorization: Bearer <resolved from webhook_headers>
{
  "tool": "lookup_order",
  "input": {
    "tenant_id": "acme",
    "order_id": "A-40912"
  },
  "user": {
    "id": "u_42",
    "name": "Alice Chen",
    "email": "alice@acme.com",
    "role": "admin",
    "company": "Acme",
    "data": { "tenant_id": "acme", "plan": "pro" }
  }
}

With webhook_method set to GET there is no body at all. The same merged object is serialized into the query string, which means every argument is visible in your access logs and in any proxy in between.

Return application/json with a 2xx status. Whatever you return is handed back to the agent verbatim as the tool result, so keep it tight and readable: the model reads it to write its reply. A response body that does not parse as JSON is treated as a failed call.

// Also HTTP 200. A 4xx is a failed call, not a readable error.
{
  "error": "order not found",
  "hint": "Ask the customer to confirm the order id."
}

Agentifys will retry your endpoint, and the rules depend on the method you configured. Read this before you point a tool at anything that writes.

Whether a failure is retried depends on whether replaying it could double-apply a write. GET, HEAD and OPTIONS count as idempotent; POST, PUT, PATCH and DELETE do not.

When the attempts are exhausted the agent receives this object as the tool result, and the conversation continues with the model knowing the tool failed. Agentifys also writes an error entry to the project logs, tagged webhook_failure, and emails a failure alert to the platform's configured alert address.

{
  "error": "TOOL_UNAVAILABLE",
  "message": "This tool is temporarily unavailable. Please try again later.",
  "detail": "HTTP 500 (attempt 1/4): upstream database timeout"
}

webhook_headers and webhook_params support {{user.*}} templating, so a tool call can be scoped to whoever is chatting without the model ever seeing the raw secret. The values come from the user context you set (see Identify users). A webhook tool has no separate auth section: credentials go in a header, like any other header.

# webhook_headers — this is where credentials belong.
Authorization: Bearer {{user.auth_token}}

# From the per-user credential vault (decrypted at call time):
X-Api-Key: {{user.creds.stripe_key}}

# From the user context data you passed:
X-Tenant-Id: {{user.data.tenant_id}}

Templating resolves only in the values of webhook_headers and webhook_params. It does not resolve in webhook_url, and it does not resolve in the arguments the model produced.

Because tools make outbound HTTP from Agentifys's servers, every webhook URL is validated on every call, not only when you save it. The URL must use https. Its hostname is resolved, and the call is refused if any resulting address is private, loopback, link-local, reserved, multicast or unspecified — which includes the cloud metadata address 169.254.169.254. Re-validating per call is what limits DNS rebinding, and refusing to follow redirects is what stops a 3xx from pivoting your credential to an unchecked host.

A blocked URL returns TOOL_UNAVAILABLE with "This tool is misconfigured and was blocked for safety." before any request is made, so the credential in your headers never leaves the server.

Reads can run freely. Writes should pause. Set requires_confirmation on a tool and the agent will not fire it silently: the call is held, the turn ends, and the widget surfaces an Approve / Cancel confirmation showing the user exactly what is about to happen and with what inputs. The next turn either runs the held call or drops it.

On the API this arrives as a confirmation_required event in the stream, carrying the tool name, its display_name, the input the model chose, and the two literal tokens you send back to resolve it. Nothing runs until the user approves.

// SSE event on a write tool awaiting approval
{
  "type": "confirmation_required",
  "id": "toolu_01H8",
  "name": "refund_charge",
  "display_name": "Refund a charge",
  "input": { "charge_id": "ch_9921", "amount": 4200 },
  "confirm": "__era_confirm__",
  "decline": "__era_decline__"
}