Custom Tools

Overview

Custom tools allow you to extend your agent’s capabilities by writing Python functions that can interact with external APIs, process data, or perform specialized tasks.

Tool Signature

Every custom tool must follow this standard signature:

def main(inputs, env_variables):
    # Your tool logic here
    return {"output": output, "capture_variables": capture_variables}

Parameters

inputs · dict

Session variables passed to the tool. These can include:

Variables from agent capture variables
Variables returned by other tools in their capture_variables dictionary
Variables from the API payload that triggered the workflow

Access pattern: inputs.get("variable_name")

env_variables · dict

Environment-specific secrets and configuration values defined in the Environment page, such as:

API keys
Authentication tokens
Database credentials

Access pattern: env_variables.get("API_KEY")

Return Value

Your tool must return a dictionary with two keys:

{
    "output": output,              # Used by the agent for decision-making
    "capture_variables": {}        # Stored in session for future use
}

output · any

The primary result of your tool’s execution. The agent uses this value to understand what the tool accomplished.

capture_variables · dict

A dictionary of variables to store in the session. These can be accessed by other agents or tools later in the workflow.

Creating a Custom Tool

1. Write Your Python Function

Navigate to the Custom Tools section and create a new tool with your Python code.

2. Add a Description

3. Example Tool

Here’s a complete example of an inventory management tool:

def main(inputs, env_variables):
    """
    Check inventory levels and return stock information.
    """
    # Get inputs
    product_id = inputs.get("product_id")
    api_key = env_variables.get("INVENTORY_API_KEY")

    # Your business logic
    import requests

    response = requests.get(
        f"https://api.inventory.com/products/{product_id}",
        headers={"Authorization": f"Bearer {api_key}"}
    )

    data = response.json()

    # Prepare output
    output = f"Product {product_id} has {data['stock']} units in stock"

    # Variables to save in session
    capture_variables = {
        "current_stock": data['stock'],
        "product_name": data['name'],
        "last_updated": data['updated_at']
    }

    return {
        "output": output,
        "capture_variables": capture_variables
    }

Tool Description Example:

Checks the current inventory level for a given product ID. Returns current stock count
and saves stock details.

Best Practices

Environment Management

Dev: Test new tools and changes
UAT: Validate with staging data
Prod: Deploy stable, tested versions

Tools automatically use environment-specific variables based on the selected environment.

Version Control

Add version numbers to your tools
Include release notes describing changes
Keep previous versions available for rollback

Error Handling

Always validate inputs before processing
Use try-except blocks for external API calls
Return meaningful error messages in the output
Store errors in output dict or capture variables dict for debugging

Testing

Test tools in Dev environment first
Validate with edge cases and invalid inputs
Monitor tool performance and errors in production
Check capture_variables are stored correctly

Publishing Tool

Develop Write and test your tool in the Dev environment. Will use env_variables values from dev.
Test Track errors in console (catch error in output)
Publish After thorough testing publish the version with version note.