Building Tools for AI Agents

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" "contact\@example com" // 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" "cheryle\@hermann walker test" } } 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