Tools allow you to connect your AI agents to APIs and external systems, enabling them to retrieve information or perform actions during customer conversations. For example, you can configure a tool to check an order status, verify registration information, or retrieve data from an internal system.
To access this feature, go to Zenvia Customer Cloud > AI Agents.
Click Tools.
Select Create tool +.
Tool configuration
In this step, you must enter the information that identifies the tool and explains how the agent should use it.
1. Ref: Enter a unique reference to identify the tool. This identifier is used by the AI model to call the tool during a conversation. Use a short name without spaces, preferably following one of these naming conventions:
kebab-case: check-order
snake_case: check_order
camelCase: checkOrder
PascalCase: CheckOrder
Example: check-order
⚠️ Attention: The reference must be unique within the organization and cannot match the reference of a native platform tool.
2. Name
Enter a name to identify the tool on the platform. Prefer clear and objective names that indicate the purpose of the integration.
Example: Check order.
3. Description
Explain what the tool does and when the agent should use it. This field is important because it guides the AI model on when to call the tool.
Example: "Checks the status of an order using the order number provided by the customer. Use this tool whenever a customer wants to know the status of a purchase."
💡Tip: Write a clear and specific description. Avoid generic wording, as the agent needs to understand when the tool is required.
4. Arguments
Click Add argument to include the required parameters. Configure the arguments according to the information required by the API you are integrating.
Arguments are the information the agent must provide to execute the tool. For example, to check an order, the agent needs to receive the corresponding order number.
Example: For an order lookup tool, you can use:
Argument: orderId.
Purpose: The identification number of the order to be checked.
The argument description should clearly specify what information the agent needs to obtain from the customer or another source.
The configured arguments are available in the request through the input namespace. For example, to use the order number provided by the agent, enter: {{input.orderId}}.
If the tool does not require any parameters, there is no need to add arguments. In this case, the model can call the tool without providing any parameters.
5. Request configuration
Define how the platform will send a request to the external API.
Before completing the fields, consult the documentation for the API you want to integrate to identify the required method, endpoint, headers, and parameters.
5.1 Method
Select the HTTP method used by the API. The method determines the type of operation to be performed.
Available methods include:
GET: Used to retrieve information.
POST: Used to send information or create records.
PUT: Used to update information.
DELETE: Used to delete records.
Example: To check an order status, select GET.
5.2 URL
Enter the API endpoint address that the tool will call. The endpoint must correspond to the operation you want to perform.
Example: https://api.example.com/orders/{{input.orderId}}
In this example, the URL uses the {{input.orderId}} variable to dynamically insert the order number provided by the agent. This allows each request to retrieve information about a different order.
⚠️ Attention: Use the URL provided in the API documentation of the system you want to integrate.
5.3 Headers
Headers allow you to send additional information in the request, such as authentication details and content format.
To add a header:
In the Headers section, click Add header.
Enter the header name.
Enter the corresponding value.
Authentication example:
In this example, the token is used to authenticate communication with the external API.
The required headers vary according to each system's documentation and authentication requirements. Confidential information, such as authentication tokens, is masked after being saved.
5.4 Body
This field allows you to configure the information that will be sent in the request body. It is primarily used with methods such as POST and PUT, when the API requires data to be submitted.
Example:
{
"orderId": "{{input.orderId}}"
}
In this example, the order number is sent in the request body.
⚠️ Attention: GET requests do not use a request body. To configure a body, select a compatible HTTP method and consult the documentation for the integrated API.
5.5 Timeout (ms)
Determines how long the platform will wait for the API response before terminating the request. This field is configured in milliseconds (ms).
Available settings:
Default value: 15,000 ms (15 seconds).
Maximum value: 60,000 ms (60 seconds).
Example: If you set the timeout to 10000, the platform will wait up to 10 seconds for the API response.
Consider the average response time of the integrated system when setting this value.
5.6 Placeholders found in the request
Displays the variables identified in the configuration.
If no placeholders are found, check whether the variables have been entered correctly in the URL, headers, or request body.
💡Tip: If you need to use information provided by the customer, configure the corresponding argument and use the {{input.argumentName}} variable in the request.
Finally, click Save.
Once registered, the tool will be available within the organization and can be associated with agents.
⚠️ Attention: Registering a tool does not mean it is automatically available to all agents. To use it, you must add it to the agent's configuration and save a new version.