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

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")

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
}

any

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

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

The tool description is critical! The agent uses it to decide when to call your tool. Be specific about:

What the tool does
When it should be used

3. Example Tool

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

inventory_tool.py

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.

Use the monitoring dashboard to identify issues early and optimize tool performance.

1. Getting Started

2. Building Assistants

3. Graph Studio (Workflow Builder)

4. DevStudio (Tool Builder)

5. Triggers & Intents

6. Builds & Environments

7. Observability & Billing

8. User Management

9. Reference

10. Troubleshooting & Support

Overview

Tool Signature

Parameters

Return Value

Creating a Custom Tool

1. Write Your Python Function

2. Add a Description

3. Example Tool

Best Practices

Publishing Tool

​Overview

​Tool Signature

​Parameters

​Return Value

​Creating a Custom Tool

​1. Write Your Python Function

​2. Add a Description

​3. Example Tool

​Best Practices

​Publishing Tool

Overview

Tool Signature

Parameters

Return Value

Creating a Custom Tool

1. Write Your Python Function

2. Add a Description

3. Example Tool

Best Practices

Publishing Tool