Custom Tools

Introduction

Custom Tools is a powerful feature that enables seamless integration between AngelX AI agents and external systems through API calls. This functionality allows you to extend the capabilities of your AI agents by connecting them to virtually any third-party service or internal system that exposes an API endpoint.

Key Concepts

What is a Custom Tool?

A Custom Tool is essentially a bridge between your AI agent and an external API endpoint. It defines:

• How the AI agent should understand and use the tool (through its name and description)
• Where the request should be sent (URL and HTTP method)
• What parameters should be included in the request (both static and dynamic)

Components of a Custom Tool

Basic Information

• custom_tool_id: Unique identifier for the tool
• agent_id: The AI agent associated with this tool
• name: A unique name for the tool (used by the AI to reference it)
• description: Detailed description explaining when and how to use the tool
• url: The API endpoint URL
• http_method: The HTTP method to use (e.g., POST)

Parameters

Static Parameters

• Fixed values that are sent with every request

Dynamic Parameters

• Values that the AI agent determines based on the context and conversation

Example Use Case

Let's look at a simple example of a custom tool that sends a conversation summary to a user:

CustomTool(
    custom_tool_id=1,
    agent_id=1,
    name="sendConversationSummary",
    description="Use this tool at the end of a conversation to send the caller a summary of the conversation.",
    url="https://foo.bar/sendSummary",
    http_method="POST",
    static_params=[
        {
            "name": "salary",
            "value": 34,
            "parameter_type": "query"
        }
    ],
    dynamic_params=[
        {
            "name": "age",
            "required": true,
            "data_type": "string",
            "description": "Age of the person",
            "parameter_type": "body"
        }
    ]
)

In this example:

• The tool is named sendConversationSummary
• It makes a POST request to https://foo.bar/sendSummary
• It includes a static query parameter salary=34 in every request
• The AI agent must provide an age value in the request body

Parameter Schema

Static Parameters

Static parameters are fixed key-value pairs that are sent with every request. The AI agent cannot modify these values. They are useful for including constants, API keys, or other fixed configuration values that shouldn't be exposed to or modified by the AI.

Each static parameter is an object with the following fields:

{
    "name": "parameterName",        # Required: Name of the parameter
    "value": "parameterValue",      # Required: Fixed value to be sent
    "parameter_type": "query"       # Required: Either "query" or "body"
}

Field	Type	Required	Description
name	string	Yes	The name of the parameter as expected by your API
value	any	Yes	The fixed value to be sent. Can be string, number, boolean, or any valid JSON value
parameter_type	string	Yes	Where to include the parameter: - "query": Added as URL query parameter - "body": Included in request body

Example of static parameters:

static_params=[
    {
        "name": "api_version",
        "value": "v2",
        "parameter_type": "query"    # Results in URL: ?api_version=v2
    },
    {
        "name": "department",
        "value": "sales",
        "parameter_type": "body"     # Included in request body: {"department": "sales"}
    }
]

Dynamic Parameters

Dynamic parameters are values that the AI agent must provide based on the conversation context. The AI uses the parameter description to understand what value to provide.

Each dynamic parameter is an object with the following fields:

{
    "name": "parameterName",        # Required: Name of the parameter
    "required": true,               # Required: Whether this parameter is mandatory
    "data_type": "string",         # Required: The expected data type
    "description": "Description",   # Required: Explains what this parameter is for
    "parameter_type": "body"        # Required: Either "query" or "body"
}

Field	Type	Required	Description
name	string	Yes	The name of the parameter as expected by your API
required	boolean	Yes	Whether the parameter must be provided
data_type	string	Yes	The expected data type. Supported types: - "string": Text values - "number": Numeric values - "boolean": True/false values
description	string	Yes	Detailed description explaining what this parameter is and when/how it should be used
parameter_type	string	Yes	Where to include the parameter: - "query": Added as URL query parameter - "body": Included in request body

Example of dynamic parameters:

dynamic_params=[
    {
        "name": "customer_id",
        "required": true,
        "data_type": "string",
        "description": "The unique identifier of the customer. Must be collected before using this tool.",
        "parameter_type": "query"
    },
    {
        "name": "transaction_details",
        "required": true,
        "data_type": "object",
        "description": "An object containing the transaction amount and description. Example: {'amount': 100, 'description': 'Payment for services'}",
        "parameter_type": "body"
    },
    {
        "name": "tags",
        "required": false,
        "data_type": "array",
        "description": "Optional list of tags to categorize the transaction",
        "parameter_type": "body"
    }
]

How Parameters Are Used

When the AI agent uses a custom tool, here's what happens:

Static Parameters

• Query parameters are automatically appended to the URL
• Body parameters are automatically included in the request body

Dynamic Parameters

• The AI analyzes the conversation context to determine appropriate values
• Required parameters must be collected before the tool can be used
• Parameters are placed in either the URL or request body based on their parameter_type

Example of a final request:

For a tool with the following configuration:

url="https://api.example.com/process",
static_params=[
    {"name": "version", "value": 2, "parameter_type": "query"}
],
dynamic_params=[
    {
        "name": "user_id",
        "required": true,
        "data_type": "string",
        "description": "User's ID",
        "parameter_type": "query"
    },
    {
        "name": "address",
        "required": true,
        "data_type": "string",
        "description": "Address of the user",
        "parameter_type": "body"
    }
]

The final request might look like:

URL: https://api.example.com/process?version=2&user_id=12345
Body: {
    "address": "21, West Sycamore Lane"
}

Best Practices for Tool Description

The description field is crucial as it guides the AI agent on when and how to use the tool.

Be Specific

• Clearly state when the tool should be used
• Define the exact purpose and use case

Include Prerequisites

• Mention any information the AI needs before using the tool
• List required data or context

Explain Outcomes

• Describe what happens when the tool is used
• Detail the expected response format

Provide Context

• Include any relevant limitations or special considerations
• Document performance characteristics and constraints

Example of a good description:

Search the product database for items matching the query string.

Use this tool when you need to find detailed product information based on keywords,
product names, or categories. The search is case-insensitive and supports fuzzy
matching to handle typos and variations in search terms.

This tool connects to the enterprise product catalog database and performs a semantic
search across all product fields, providing comprehensive results with all available
product metadata.

Example response:
    [
        {
            "id": "P12345",
            "name": "Ultra Comfort Running Shoes",
            "description": "Lightweight running shoes with...",
            "price": 89.99,
            "category": ["Footwear", "Athletic", "Running"]
        },
        ...
    ]

Notes:
    - This tool only searches the product catalog and does not provide
        inventory or availability information
    - Results are cached for 15 minutes to improve performance
    - The search index updates every 6 hours, so very recent products may not appear
    - For real-time inventory status, use a separate inventory check tool

Args:
    query: The search string (product name, category, or keywords)
            Example: "red running shoes" or "smartphone charger"
    max_results: Maximum number of results to return (default: 10, range: 1-100)
                    Use lower values for faster response when exact matches are expected

Returns:
    A list of matching product records, each containing:
    - id: Unique product identifier (string)
    - name: Product name (string)
    - description: Detailed product description (string)
    - price: Current price in USD (float)
    - category: Product category hierarchy (list)