Building Tools for AI Agents

10 min

This document outlines how to integrate custom endpoints with AI Agents, enabling them to access external data and perform specific actions. Tooling allows you to extend the capabilities of your AI Agents beyond their built-in functionalities.

Overview

Tools are HTTP endpoints that your AI Agents will make requests to, to retrieve information or trigger actions. You can add multiple tools for your AI agents, and Peach will automatically invoke these calls on behalf of your AI agents.

Tool Endpoint Requirements

Each tool endpoint must adhere to the following requirements:

HTTP Methods: The endpoint must support a GET and a POST request.
Data Format: All data exchanged with the endpoint must be in JSON format.
Authentication: Implement appropriate authentication mechanisms to secure your endpoints.

GET Request: Function Declaration

A GET request to the endpoint should return a JSON object containing a function_declarations array. This array describes the functions that the AI Agent can call through this endpoint.

Response Structure:

{
  "function_declarations": [
    {
      "name": "function_name",
      "description": "A concise description of the function's purpose.",
      "parameters": {
        "type": "object",
        "properties": {
          "parameter_name": {
            "type": "string",
            "description": "Description of the parameter.",
            "enum": ["value1", "value2"] // Optional: List of allowed values.
          },
          // ... more parameters ...
        },
        "required": ["parameter1", "parameter2"] // Array of required parameter names.
      }
    },
    // ... more function declarations ...
  ]
}

Example:

{
  "function_declarations": [
    {
      "name": "find_service_points",
      "description": "Returns a list of service points near the provided pincode.",
      "parameters": {
        "type": "object",
        "properties": {
          "pincode": {
            "type": "string",
            "description": "Nearest pincode."
          }
        },
        "required": ["pincode"]
      }
    },
    {
      "name": "get_service_packages",
      "description": "This method fetches service packages based on the vehicle model and year.",
      "parameters": {
        "type": "object",
        "properties": {
          "vehicle_model": {
            "type": "string",
            "description": "The model of the vehicle."
          },
          "vehicle_year": {
            "type": "integer",
            "description": "The year the vehicle was manufactured."
          }
        },
        "required": ["vehicle_model", "vehicle_year"]
      }
    }
  ]
}

Field Descriptions:

function_declarations: An array of function objects.
name: The unique name of the function. This is how the AI Agent identifies the function to call.
description: A human-readable description of the function. This helps the AI Agent understand the function's purpose.
parameters: Defines the input parameters for the function.
- type: The data type of the parameters object (always "object").
- properties: An object containing definitions for each parameter.
  - parameter_name: The name of the parameter.
  - type: The data type of the parameter (e.g., "string", "integer", "boolean").
  - description: A human-readable description of the parameter.
  - enum: (Optional) An array of allowed values for the parameter.
- required: An array of parameter names that are required for the function call.

POST Request: Function Execution

When the AI Agent needs to execute a function, it will make a POST request to your tool endpoint. The request body will contain the function name, arguments, and contact information.

Request Body Structure:

{
  "name": "function_name",
  "arguments": {
    "parameter1": "value1",
    "parameter2": "value2"
    // ... more arguments ...
  },
  "contact": {
    "id": 123,
    "account_id": 456,
    "name": "Contact Name",
    "phone_number": "+15551234567",
    "email": "[email protected]"
    // ... more contact details ...
  }
}

Example:

{
  "name": "find_service_points",
  "arguments": {
    "pincode": "560001"
  },
  "contact": {
    "id": 18,
    "account_id": 1,
    "name": "Florance Satterfield",
    "phone_number": "+13194648432",
    "first_name": "Florance",
    "last_name": "Satterfield",
    "country_code": "1",
    "language": null,
    "email": "[email protected]"
  }
}

Field Descriptions:

name: The name of the function to execute. This must match a name defined in the function_declarations returned by the GET request.
arguments: An object containing the values for the function's parameters. The keys in this object must match the parameter_name values defined in the function_declarations.
contact: An object containing information about the contact associated with the request. This can be used for personalization or authorization purposes.

Adding an Endpoint

To add tools for your AI Agent:

Navigate to the "Tools" section within the AI Agent screen.
Click the "Add Custom Tool" option.
Enter the URL of your endpoint. Add any necessary authentication headers.
Save the tool.
Turn on/off the functions that the AI agent should have access to.

The AI Agent will then automatically make use of available functions in conversations.

Best Practices

Keep Descriptions Clear and Concise: Use clear and concise descriptions for your functions and parameters. This will help the AI Agent understand how to use them effectively.
Implement Robust Error Handling: Implement robust error handling in your endpoints to gracefully handle invalid input or unexpected errors.
Secure Your Endpoints: Implement appropriate authentication mechanisms to protect your endpoints from unauthorized access.
Test Thoroughly: Thoroughly test your endpoints to ensure that they are working correctly and that the AI Agent is using them as expected.

By following these guidelines, you can effectively integrate your services with your AI Agents and extend their capabilities to meet your specific needs.

Example

Here’s an example function declaration of an Image Generation tool with the associated Conversation prompt:

Function declaration:

{
  "function_declarations": [
    {
      "name": "render_certificate",
      "description": "Returns a media_link of the rendered certificate image.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer_name": {
            "type": "string",
            "description": "The Customer's provided name."
          },
          "image_orientation": {
            "type": "string",
            "description": "The orientation of the image. The allowed values are 'landscape' and 'portrait'. The default value is 'portrait'. The template used to render the image is determined by the value of the image_orientation parameter."
          },
          "customer_name_size": {
            "type": "integer",
            "description": "The font size of the text in the image in pixels. The default value is 48. The value always has to be greater than 0."
          }
        },
        "required": [
          "customer_name",
          "image_orientation",
          "customer_name_size"
        ]
      }
    }
  ]
}

Conversation prompt:

You are a friendly, conversational agent. Engage the user with warm, 
open-ended questions,clarify user requirements naturally, 
and maintain an interactive dialogue.

You are helping the customer generate a certificate for their participation 
in an awareness program.

Ask the full name to be used on the certificate.

Create and share the certificate in portrait format.
Don't mention the word portrait during the chat.

Use the `media_link` returned as part of the `render_certificate` 
tool's response as the media_url for sending the image as part of the message.