Skip to main content
Tools are functions that an AI agent can invoke during a call. They extend the agent’s capabilities beyond conversation — making API calls, transferring calls, extracting data, and more.

​
Tool types

TalkPilot supports 7 tool types:
TypeDescription
http_requestMake HTTP requests to external APIs (CRM lookup, ticket creation)
transfer_callCold or warm call transfer to a phone number
monitored_transferSIP INVITE transfer with call monitoring
end_callEnd the call with an optional goodbye message
extract_variableExtract structured data from the conversation (email, phone, etc.)
play_tonePlay DTMF tones (for IVR navigation)
knowledge_baseSearch the agent’s knowledge base documents

​
Data model

FieldTypeDescription
iduuidTool identifier
agent_iduuidParent agent
namestringInternal name for LLM function calling (max 100 chars)
display_namestringHuman-readable name (max 255 chars)
descriptionstringDescription shown to the LLM (max 2,000 chars)
tool_typestringOne of the 7 types above
configobjectTool-specific configuration (see below)
is_enabledbooleanWhether the tool is active
priorityintegerExecution priority (lower = higher priority)
created_atdatetimeCreation timestamp
updated_atdatetimeLast update timestamp

​
Tool configurations

​
http_request

Make HTTP requests to external APIs during a call. 
{
  "url": "https://crm.example.com/api/customers",
  "method": "GET",
  "headers": [
    { "key": "Authorization", "value": "Bearer {{API_KEY}}" }
  ],
  "query_params": [
    { "key": "phone", "value": "{{caller_phone}}" }
  ],
  "timeout": 30,
  "speak_during_execution": true,
  "speak_after_execution": true
}
Config fieldTypeDescription
urlstringTarget URL (SSRF-protected — no internal IPs)
methodstringGET, POST, PUT, DELETE
headersarrayKey-value header pairs
query_paramsarrayKey-value query parameters
timeoutnumberRequest timeout in seconds
speak_during_executionbooleanAgent speaks while waiting for response
speak_after_executionbooleanAgent speaks the result to the caller

​
transfer_call

Transfer the call to a human agent or external number. 
{
  "phone_number": "+4930999888",
  "transfer_mode": "cold",
  "play_hold_music": false
}
Config fieldTypeDescription
phone_numberstringTarget phone number
transfer_modestringcold (immediate) or warm (agent stays on line)
play_hold_musicbooleanPlay music while transferring

​
monitored_transfer

SIP INVITE transfer with monitoring — the AI stays on the line to monitor the transfer. 
{
  "phone_number": "+4930999888",
  "timeout_seconds": 20
}

​
end_call

Terminate the call with an optional goodbye message. 
{
  "goodbye_message": "Vielen Dank fuer Ihren Anruf. Auf Wiederhoeren!"
}

​
extract_variable

Extract structured data from the conversation. 
{
  "variable_name": "email",
  "variable_type": "email",
  "prompt_text": "Bitte nennen Sie mir Ihre E-Mail-Adresse.",
  "example_format": "name@example.com",
  "confirmation_enabled": true
}
Config fieldTypeDescription
variable_namestringName of the extracted variable
variable_typestringemail, phone, name, number, date, custom
prompt_textstringWhat the agent asks to extract the data
example_formatstringExample shown to the LLM
confirmation_enabledbooleanAsk the caller to confirm the extracted value

​
play_tone

Play DTMF tones for IVR navigation. 
{
  "tone_type": "dtmf",
  "dtmf_digit": "1",
  "duration": 500,
  "volume": 0.8
}

​
knowledge_base

Search the agent’s knowledge base using RAG (Retrieval-Augmented Generation). 
{
  "top_k": 5,
  "similarity_threshold": 0.7,
  "bridging_sentence": "Einen Moment, ich schaue kurz nach..."
}
Config fieldTypeDescription
top_knumberNumber of document chunks to retrieve
similarity_thresholdnumberMinimum similarity score (0-1)
bridging_sentencestringWhat the agent says while searching

​
Endpoints

​
List tools

GET /v1/agents/{agentId}/tools
Permission: tools:read | Pagination: no (returns all tools)

​
Get tool

GET /v1/agents/{agentId}/tools/{toolId}
Permission: tools:read

​
Create tool

POST /v1/agents/{agentId}/tools
Permission: tools:write Required fields: name, description, tool_type, config Returns 409 Conflict if a tool with the same name already exists for the agent. 
curl -X POST -H "X-API-Key: $TP_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "lookup_customer",
    "display_name": "Kunden-Lookup",
    "description": "Looks up customer info by phone number",
    "tool_type": "http_request",
    "config": {
      "url": "https://crm.example.com/api/customers",
      "method": "GET",
      "headers": [{"key": "Authorization", "value": "Bearer YOUR_KEY"}],
      "timeout": 30,
      "speak_during_execution": true,
      "speak_after_execution": true
    },
    "priority": 1,
    "is_enabled": true
  }' \
  "$TP_BASE/agents/{agentId}/tools"

​
Update tool

PATCH /v1/agents/{agentId}/tools/{toolId}
Permission: tools:write

​
Delete tool

DELETE /v1/agents/{agentId}/tools/{toolId}
Permission: tools:write | Returns 204 No Content