Real-Time AgentsAgent Tools

Create Tool

Create a new tool for an agent. Tools can be webhook tools (call external APIs) or client tools (trigger client-side actions). System tools cannot be manually created.

HTTP Request

$POST https://app.resemble.ai/api/v2/agents/{agent_uuid}/tools

URL Parameters

ParameterTypeDescription
agent_uuidstringThe agent’s UUID

Request Body

AttributeTypeRequiredDescription
namestringYesUnique tool name (per agent)
descriptionstringYesDescription for LLM (min 1 character)
tool_typestringYesTool type: “webhook” or “client”
tool_configobjectYesTool configuration (see below)

Note: tool_type: "system" is not allowed. System tools are automatically created by the platform.

Webhook Tool Example

$curl --request POST "https://app.resemble.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/tools" \
>  -H "Authorization: Bearer YOUR_API_TOKEN" \
>  -H "Content-Type: application/json" \
>  --data '{
>    "name": "check_weather",
>    "description": "Check weather for a given location and store the temperature",
>    "tool_type": "webhook",
>    "tool_config": {
>      "api_schema": {
>        "url": "https://api.weather.com/check?location={{location}}",
>        "method": "GET",
>        "request_headers": {
>          "Authorization": "Bearer {{weather_api_key}}"
>        }
>      },
>      "parameters": {
>        "location": {
>          "type": "string",
>          "description": "City name to check weather for"
>        }
>      },
>      "assignments": [
>        {
>          "source": "response",
>          "attribute_name": "temperature",
>          "dynamic_variable": "current_temp"
>        }
>      ],
>      "response_timeout_secs": 30
>    }
>  }'

Client Tool Example

$curl --request POST "https://app.resemble.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/tools" \
>  -H "Authorization: Bearer YOUR_API_TOKEN" \
>  -H "Content-Type: application/json" \
>  --data '{
>    "name": "show_product",
>    "description": "Display product details to the customer",
>    "tool_type": "client",
>    "tool_config": {
>      "parameters": {
>        "product_id": {
>          "type": "string",
>          "description": "Product identifier"
>        }
>      },
>      "assignments": [
>        {
>          "source": "argument",
>          "attribute_name": "product_id",
>          "dynamic_variable": "displayed_product"
>        }
>      ],
>      "return_message": "Product displayed to customer",
>      "disable_interruptions": false,
>      "force_pre_tool_speech": false
>    }
>  }'

Webhook Tool Configuration

AttributeTypeRequiredDescription
api_schemaobjectYesAPI endpoint configuration
parametersobjectNoTool parameters for LLM
assignmentsarrayYesVariable assignments from response
response_timeout_secsintegerNoTimeout in seconds (1-60, default: 30)

API Schema

AttributeTypeRequiredDescription
urlstringYesHTTP/HTTPS URL (supports {{variable}} templating)
methodstringYesHTTP method: GET, POST, PUT, PATCH, DELETE
request_headersobjectNoHTTP headers (supports {{variable}} templating)
request_bodyobjectNoRequest body for POST/PUT/PATCH

Client Tool Configuration

AttributeTypeRequiredDescription
parametersobjectYesTool parameters for LLM
assignmentsarrayYesVariable assignments from arguments
return_messagestringYesMessage to return after execution
disable_interruptionsbooleanYesPrevent interruptions during execution
force_pre_tool_speechbooleanYesForce agent speech before tool use

Response (Success)

1{
2  "success": true,
3  "item": {
4    "id": 1,
5    "name": "check_weather",
6    "description": "Check weather for a given location and store the temperature",
7    "tool_type": "webhook",
8    "tool_config": {
9      "api_schema": {
10        "url": "https://api.weather.com/check?location={{location}}",
11        "method": "GET"
12      },
13      "parameters": {
14        "location": {
15          "type": "string",
16          "description": "City name to check weather for"
17        }
18      },
19      "assignments": [
20        {
21          "source": "response",
22          "attribute_name": "temperature",
23          "dynamic_variable": "current_temp"
24        }
25      ],
26      "response_timeout_secs": 30
27    },
28    "active": true,
29    "created_at": "2025-01-27T10:00:00Z",
30    "updated_at": "2025-01-27T10:00:00Z"
31  },
32  "message": "Tool created successfully"
33}

Response (Error)

1{
2  "success": false,
3  "errors": {
4    "name": ["has already been taken"],
5    "description": ["can't be blank"],
6    "tool_config": [
7      "api_schema.url must be a valid HTTP or HTTPS URL",
8      "assignments[0].dynamic_variable 'current_temp' does not exist in agent's dynamic_variables",
9      "api_schema contains templated variable '{{weather_api_key}}' that does not exist in parameters or agent's dynamic_variables"
10    ]
11  },
12  "message": "Failed to create tool"
13}

See Also