Real-Time AgentsAgent Tools

Agent Tools

Tools extend agent capabilities by allowing them to call external APIs (webhook tools), trigger client-side actions (client tools), or use platform-provided functionality (system tools).

Tool Types

Webhook Tools

Call external HTTP APIs during conversations.

Use Cases:

  • Check inventory availability
  • Fetch customer data from CRM
  • Process payments
  • Update databases
  • Trigger notifications

Features:

  • Full HTTP method support (GET, POST, PUT, PATCH, DELETE)
  • Custom headers and request bodies
  • Template variable substitution with {{variable_name}}
  • Response data extraction and assignment to dynamic variables
  • Configurable timeouts (1-60 seconds)

Client Tools

Trigger client-side actions in your application.

Use Cases:

  • Display product information
  • Show images or videos
  • Update UI components
  • Navigate to different screens
  • Collect user input

Features:

  • Parameter passing to client application
  • Dynamic variable assignment from arguments
  • Custom return messages
  • Interruption control

System Tools

Platform-provided tools for common operations.

Available System Tools:

  • end_call: End the current phone call
  • transfer_to_number: Transfer call to another number
  • voicemail_detection: Detect if call reached voicemail

Features:

  • Automatically created for each agent
  • Cannot be manually created or deleted
  • Can be enabled/disabled and configured
  • See Get System Tools for details

Tool Configuration

Parameters

Define what information the LLM should collect before using the tool:

1{
2  "parameters": {
3    "location": {
4      "type": "string",
5      "description": "City name to check weather for"
6    },
7    "units": {
8      "type": "string",
9      "description": "Temperature units: celsius or fahrenheit"
10    }
11  }
12}

Assignments

Extract data from tool responses and assign to dynamic variables:

1{
2  "assignments": [
3    {
4      "source": "response",
5      "attribute_name": "temperature",
6      "dynamic_variable": "current_temp"
7    }
8  ]
9}

Sources:

  • response: Extract from webhook HTTP response
  • argument: Extract from tool arguments (client tools only)

Behavior Control

Control how tools execute:

SettingTypeDescription
activebooleanEnable/disable the tool
disable_interruptionsbooleanPrevent user interruptions during tool use
force_pre_tool_speechbooleanForce agent to speak before using tool
return_messagestringMessage to return after execution (client tools)
response_timeout_secsintegerTimeout for webhook calls (1-60 seconds)

Template Variables

Use {{variable_name}} syntax to inject dynamic values:

Available in:

  • Webhook URLs
  • Request headers
  • Request bodies

Variable Sources:

  • Tool parameters (defined in the tool)
  • Agent dynamic variables
  • Built-in variables (e.g., {{agent_uuid}}, {{conversation_uuid}})

Example:

1{
2  "api_schema": {
3    "url": "https://api.example.com/customers/{{customer_id}}",
4    "request_headers": {
5      "Authorization": "Bearer {{api_key}}"
6    }
7  }
8}

Available Operations

Common Workflows

Creating a Webhook Tool

  1. Define the external API endpoint
  2. Specify parameters the LLM should collect
  3. Configure request headers/body with template variables
  4. Set up assignments to extract response data
  5. Configure timeout and behavior settings

Creating a Client Tool

  1. Define parameters for the client action
  2. Set up assignments to pass data to dynamic variables
  3. Configure return message
  4. Set interruption and speech behavior

Updating System Tools

  1. System tools are auto-created (cannot manually create)
  2. Update via agent creation/update
  3. Can only modify: active, disable_interruptions, force_pre_tool_speech

Validation Rules

  • Tool names must be unique per agent
  • Dynamic variables referenced in assignments must exist in agent configuration
  • Template variables in URLs/headers/bodies must exist in parameters or agent dynamic variables
  • Webhook URLs must be valid HTTP/HTTPS endpoints
  • HTTP methods must be: GET, POST, PUT, PATCH, DELETE
  • System tools cannot be manually created or deleted

See Also