On this page

Tools

Tools in the Twilio AI Assistant framework are specialized APIs that enable your Assistant to perform specific tasks, such as retrieving real-time data, processing orders, or executing complex operations.

Unlike Knowledge, which provides unstructured data for context and information retrieval, Tools are designed to perform actionable tasks that help the Assistant solve targeted problems. Each Tool is purpose-built, and the Assistant selects the most appropriate Tool based on the user's request.

Tools function similarly to webhooks: when a user makes a specific request, the Assistant triggers the appropriate Tool, which then performs an API call to the relevant service. The Assistant processes the response and delivers it to the user in a conversational manner.

Configure Tools

Configuring Tools for your AI Assistant involves setting up several attributes that define how the Tool interacts with external APIs.

Tool attributes

Attribute name	Description	Example
Name	A unique identifier for your Tool within the Twilio Console.	Weather Check
Description	A brief explanation of the Tool's purpose and function. This description helps the Assistant determine when to use the Tool.	Fetches the current weather information based on the provided location
HTTP method	Whether the API request should be an HTTP `GET` or `POST` request. Any response returned from the HTTP endpoint feeds back into the model. For example, you could return plain text from your Tool that provides further instructions for the model: "Tell the user this resource isn't available".	`GET`
Webhook URL	The endpoint URL for the request. This URL handles the business logic and interacts with the external API.	`https://api.open-meteo.com/v1/forecast`
Input schema	The parameters required for the Tool to function. These parameters, often derived from user input, are passed to the Tool's API endpoint. The schema format is similar to TypeScript types. Note that the full input schema definition is available to the model, including the comments.	`export type Data = {latitude: number; longitude: number;}`
Requires User Verification	Indicates whether customer verification is required (with Twilio Verify) before the Assistant can use the Tool.	[unchecked]
Authorization Provider	One of: `Basic Auth`, `Auth Token`, `OAuth2.0 Password Grant`, `Custom Auth Header`. What type of authorization the API request requires, and the relevant values if specified.	`Basic Auth`

(warning)

Warning

AI Assistants is currently not following any HTTP redirects that your Webhook URL might return. This means that if your Webhook URL originally returns an HTTP status code of 301, 302, 307, or 308 with a different URL to visit instead, AI Assistants will not visit the subsequent URL. As an example: The URL https://twilio.com/ redirects to https://www.twilio.com/en-us when you visit it in the browser. AI Assistants currently does not follow such a behavior and so https://twilio.com/ would not be a valid Webhook URL and instead you would need to use https://www.twilio.com/en-us directly.

Security and authentication

(information)

Info

For added security and flexibility, Twilio recommends creating a proxy API endpoint to handle sensitive credentials, which the Assistant can access instead of directly interacting with external APIs. You can do this using Twilio Functions, which lets you host Node.js code directly within Twilio. Check out sample Tools built for Twilio Functions.

Implement security measures to ensure your Tool interacts safely with external services:

Authentication: Out of the box, Tools support various auth methods, including OAuth 2.0 and Basic Authentication.
Request validation: Use the X-Twilio-Signature header to validate that requests are coming from Twilio.
Input validation: Define input schemas that the AI will automatically validate before making API requests, ensuring that all inputs conform to the expected structure.
Data minimization: Think of your LLM as an untrusted client application: ensure your Tool API only returns data that you're comfortable displaying to the end user. Keeping the amount of data returned from the Tool to a minimum will also improve latency.
HTTP headers: With every HTTP request we will automatically pass the following information as HTTP headers to the request. The AI cannot manipulate these and therefore you can use them to implement access controls to limit on whose behalf the AI can perform actions.

Name	Description	Example
`X-Session-Id`	The session ID of your conversation. You can use this for example to identify if the Assistant called the same Tool multiple times from the same conversation.
`X-Identity`	Used to validate the user's identity and correlates to the Segment identity used for Customer Memory. If you use the Assistant Simulator, this value will be the same as what you put into the User Identity field.	`email:demo@example.com`
`X-Twilio-Signature`	A Twilio request signature that you can use to validate the request came from Twilio.

Use cases

You can use Tools in various scenarios to enhance the capabilities of your AI Assistant:

Dynamic real-time information retrieval: For example, a Tool can fetch weather updates, stock prices, or news headlines from external APIs.
Operations: Tools can handle tasks such as booking a service, placing an order, or updating a customer record.
Calculations: Use Tools to execute complex calculations, unit conversions, or generate financial estimates by interfacing with specialized APIs.