Custom Tools

A Custom Tool is a user-defined HTTP call that an AI agent (or a dedicated node) can invoke. Use custom tools to give agents access to your own APIs and services without writing runtime code.

Defining a custom tool

A custom tool stores a name, description, HTTP method, URL, headers, and an optional body template, plus an enabled flag. Create and manage them in the Custom Tools view or through the custom-tools API.

Templating. Interpolate the agent's input into the URL, headers, and body with placeholders:

• {{input}} — the whole input
• {{input.path.to.field}} — a nested field

Secrets. Reference stored workspace credentials with {{credential.NAME}} (also {{secret.NAME}} / {{secrets.NAME}}). Confluye resolves required secrets before the call and fails fast if an input or secret is missing, so credentials never appear inline in the tool definition.

Testing a tool

Test a tool before using it in production with POST /api/custom-tools/{id}/test (and the v1 equivalent). The test resolves workspace secrets, performs the request with a default 15-second timeout, and returns a structured result with the status, latency, and response body. GET/HEAD requests send no body; other methods send JSON or the rendered body template.

Using tools in agents

There are two ways a custom tool runs:

1. 1

   From an AI agent block

   Add the tool to the agent's customToolIds. The agent can then call it as a tool during its reasoning, with the model deciding when to invoke it.

2. 2

   As a dedicated node

   Use the Custom Tool node and set its customToolId to call the tool directly as a workflow step.

Next steps