Reference

Custom tools

Give your agents a new capability without writing platform code: a custom tool is a declarative HTTP call you define in the app, that runs through the same approval gate, guardrails and audit log as any built-in tool.

What a custom tool is

A custom tool is a declarative HTTP-call definition that an agent can call to reach an external system: a method, a URL, and optional headers, query parameters and body. There is no code-execution surface. Request fields are built from validated agent input by simple {token} substitution, never an expression language or arbitrary code.

When you save a tool, SyftOS registers it in your tenant's tool registry under the namespaced slug custom.{slug}. From that point it behaves exactly like a native tool. It can be assigned to agents, and every call is governed.

Defining a tool

From the custom tools list, choose to add a tool and complete the authoring form. The key fields are:

• Name and slug: the slug is lowercase letters, numbers and underscores (2–48 characters) and must be unique within your tenant; it becomes the registry slug custom.{slug}.
• Description: what the tool does. The agent reads this to decide when to use it, so be precise.
• HTTP method: one of GET, POST, PUT, PATCH or DELETE.
• URL template: the endpoint, with {token} placeholders filled from the agent's input. Only https URLs that pass the SSRF guard are permitted.
• Header, query and body templates: optional objects whose values may also contain {token} placeholders.
• Input schema: a JSON Schema (object-rooted) describing the input the agent must supply. This is what the runtime validates before any substitution.
• Success path: an optional dotted path (e.g. data.id) used to pull the meaningful value out of the response.
• Timeout: request timeout in seconds (1–120; defaults to the platform value, typically 30).
• Enabled: whether agents can call the tool. New tools are enabled by default.

Authentication and credentials

Authentication is optional — a tool calling a public API needs none. To authenticate, supply an auth type (API key or OAuth) and a token. The token is write-only: it is validated, optionally verified, then stored encrypted at rest in a dedicated credential vault and is never echoed back to any screen, prop, job payload or audit entry.

• The tool list and edit form show the credential type (API key or OAuth) and when it was last rotated, never the secret itself.
• Rotation: a tool holds at most one live credential; saving a new token supersedes the old one.
• On edit, leaving the token field empty keeps the stored secret untouched. You do not need to re-enter it to change other fields.

Verify before saving

You can ask SyftOS to verify a candidate before it is stored. Verification screens the endpoint against the SSRF guard and dry-tests the live call using sample input you provide. If it fails, you get a validation error against the URL and nothing is saved — no definition, no credential. The URL is also SSRF-screened at save time and re-screened on every real call.

Governance, risk and permissions

Two governance fields are mandatory, mirroring native tool registration:

• Side effect: whether a call changes external state. A side-effecting custom tool call is proposed as an agent action and held at the approval centre for a human decision; agents never approve their own actions.
• Risk level: the tool's risk classification. A high-risk tool is never auto-approvable.

The entire surface (viewing, creating, editing, verifying and deleting) is gated by the Manage integrations permission, which only owners and admins hold. Custom tools belong to your tenant: another tenant's tool is never visible and resolves as not found. Every create, update and delete is written to the append-only audit log, and the edit page shows the recent history for that tool.

Deleting a tool removes it from the registry so agents can no longer call it.

Next steps