Skip to main content
Custom tools allow you to extend the agent’s capabilities by registering functions that it can call during execution. When the agent needs to perform an action that your tool provides, it will pause and wait for you to execute the tool and return the result.

How Custom Tools Work

  1. Register tools when creating a task via the custom_tools parameter
  2. Poll for tool calls - the agent sends tool_call events when it needs to use a tool
  3. Execute the tool locally and return the result via the Event endpoint
  4. Agent continues with the tool’s output

Step 1: Define Your Tools

When creating a task, define your custom tools using the custom_tools parameter:

Tool Definition Schema

Step 2: Poll for Tool Calls

When the agent needs to call one of your tools, it emits a tool_call event. Poll the task endpoint to receive these events:
Response with tool call:
Important: The id field in the event is crucial - you’ll use it to send the response.

Step 3: Execute and Respond

Execute the tool locally, then send the result back via the Event endpoint:

Response Format

Handling Errors

If your tool fails, return an error:
The agent will receive the error and may try again with corrected input or take an alternative approach.

Complete Example: Weather Bot

Here’s a complete implementation that handles custom tool calls:

Using with Sessions

Custom tools work the same way with session workflows. Define them when creating the session:
Then when running tasks within the session, the agent can use your custom tools:

Python SDK Example

The SDK provides a decorator-based approach for custom tools:

Best Practices

  1. Write clear descriptions - The agent uses descriptions to decide when to call your tool
  2. Define complete schemas - Include all required fields and descriptions for each input
  3. Handle errors gracefully - Return meaningful error messages so the agent can recover
  4. Set appropriate timeouts - Long-running tools should be async with proper timeout handling
  5. Validate inputs - Check that required fields are present before executing