Agent Tools

Manage custom tools and tool assignments for voice agents.

Tools Guide

Tools extend your agents' capabilities by allowing them to perform actions beyond conversation. When an agent determines a tool is needed, it automatically invokes the appropriate tool with parameters extracted from the conversation.

Tool Types

HTTP Tools

HTTP tools execute on your server via HTTP requests. When invoked, the system sends an HTTP request to your configured endpoint with the extracted parameters.

Execution Flow:

Agent determines tool is needed during conversation
System sends HTTP request to your endpoint
Your server processes request and returns JSON response (must complete within 6 seconds)
Agent receives response and continues conversation

Best for:

Database queries and updates
External API integrations
Payment processing
Server-side business logic
CRM integrations

Key characteristics:

Work with all call types (WebRTC, WebSocket, telephony)
6-second timeout
Parameters can be sent in header, query, path, or body
Secure server-side execution

Client Tools

Client tools execute in your client application via WebSocket messages. When invoked, the system sends a client_tool_invocation message to your WebSocket connection.

Execution Flow:

Agent determines client tool is needed
System sends client_tool_invocation message via WebSocket
Your client receives message and executes logic
Your client sends client_tool_result message back
Agent receives result and continues conversation

Best for:

Call transfers and forwarding
UI updates and notifications
Client-side state management
Real-time visual feedback
Device control (camera, microphone)

Key characteristics:

Only work with WebRTC and WebSocket calls
No timeout restrictions
Lower latency (no server round-trip)
Direct UI control
Parameters sent via WebSocket (no location field needed)

Why Client Tools Are Essential for Telephony/SIP:

When integrating with SIP systems, HTTP tools cannot work because:

SIP call is connected via WebSocket (audio stream)
HTTP tool fires to your server on a separate connection
Your server has no way to map the HTTP request to the active SIP call
Cannot control which call to forward or transfer

Client tools solve this by sending the invocation on the SAME WebSocket connection as the audio, so your SIP system knows exactly which call to act on.

Example Use Case - Lead Qualification:

Customer calls in → SIP connects via WebSocket → Agent qualifies lead during conversation → Agent invokes client tool with qualification data → Your SIP system receives client_tool_invocation on the active call connection → Your system forwards call to sales team → Sends client_tool_result back → Agent continues or ends call.

Parameters

Dynamic Parameters

Values the AI extracts from conversation. Different for each invocation. Configure with:

type: string, number, boolean, object, array
description: Helps AI understand what to extract
required: Whether parameter must be provided
enum: Optional list of allowed values
location (HTTP tools only): header, query, path, or body

Automatic Parameters

Values provided automatically by the system. Same for every invocation. Hidden from the AI.

Use for API keys, user context, session data
Configure with knownValue field
location field required for HTTP tools

WebSocket Protocol (for Client Tools)

Client tools use WebSocket messages for communication. The WebSocket connection established by /calls/create with medium=websocket carries both binary audio frames and text JSON messages.

Message Types

Messages You Receive (Server → Client)

These are JSON text messages sent from the server to your client application via WebSocket.

1. client_tool_invocation

Sent when the agent invokes a client tool. Your client must handle this and send back a client_tool_result.

Structure:

type: "client_tool_invocation"
invocationId: Unique identifier for matching your response
toolName: The modelToolName of the tool being invoked
parameters: Object with parameter values extracted from conversation

2. state

Sent when agent changes state.

Structure:

type: "state"
state: One of "idle", "listening", "thinking", "speaking"

Use this to show visual indicators (e.g., microphone icon, thinking spinner, speaking animation).

3. call_started

Sent when call is initialized and ready.

Structure:

type: "call_started"
callId: Unique call identifier

Use this to know when the call is active and ready for interaction.

Messages You Send (Client → Server)

These are JSON text messages your client sends to the server via WebSocket.

client_tool_result

Your response after executing a client tool. Send this after receiving client_tool_invocation.

Success Response Structure:

type: "client_tool_result"
invocationId: Must match the invocationId from the client_tool_invocation you received
result: String with execution result
responseType: "tool-response" (optional, defaults to this)

Error Response Structure:

type: "client_tool_result"
invocationId: Must match the invocationId from the client_tool_invocation you received
errorType: "implementation-error" or "undefined"
errorMessage: Human-readable error description

Critical: You MUST send a client_tool_result for every client_tool_invocation you receive. Use the exact same invocationId. The agent waits for this response to continue the conversation.

Audio Format

Format: Binary WebSocket frames carry PCM s16le (signed 16-bit little-endian PCM) audio data at the sample rates specified in the call creation request.

For SIP/Telephony Integrations:

SIP systems typically use G.711 ulaw (8kHz, 8-bit compressed). You must transcode between formats:

SIP → Ultravox: Convert G.711 ulaw to PCM s16le at your specified inputSampleRate
Ultravox → SIP: Convert PCM s16le at outputSampleRate to G.711 ulaw

Common SIP configuration uses 8000 Hz for both input and output sample rates.

Best Practices

HTTP Tools

Optimize endpoints to respond within 6 seconds
Return clear error messages for failures
Use automatic parameters for API keys and secrets
Validate all inputs on your server
Use HTTPS for all endpoints

Client Tools

Always send client_tool_result for every invocation
Use exact invocationId from invocation message
Handle errors gracefully with error objects
Monitor WebSocket connection health
Implement reconnection logic

Tool Design

Use descriptive modelToolName values (camelCase)
Each tool should have one clear purpose
Write detailed descriptions explaining when to use the tool
Use enums for parameters with limited valid values
Mark parameters as required only if tool cannot function without them

List agent tools

get

Retrieve all custom tools created for voice agents.

Tool Types

Tools can be filtered by type using the type parameter:

type=http - Returns only HTTP tools (call external APIs)
type=client - Returns only client tools (run in browser, invoked via WebSocket messages)
No type filter - Returns all tools

Response Format

HTTP tools include httpMethod and baseUrlPattern fields. Client tools omit HTTP-specific fields. Both types include parameters with appropriate structure for their use case.

Authorizations

X-API-KeystringRequired

API key for authentication

Query parameters

pageinteger · min: 1Optional

Page number for pagination

Default: 1

limitinteger · min: 1 · max: 100Optional

Number of items per page

Default: 50

searchstringOptional

Search tools by name, description, or model name

typestring · enumOptional

Filter tools by type

Possible values:

Responses

200

Successful response

application/json

get

/agent-tools

GET /api/v1/agent-tools HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Accept: */*

200

Successful response

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "description": "text",
      "modelToolName": "text",
      "type": "http",
      "httpMethod": "GET",
      "baseUrlPattern": "text",
      "automaticParameters": {
        "ANY_ADDITIONAL_PROPERTY": {
          "location": "header",
          "knownValue": "text"
        }
      },
      "dynamicParameters": {
        "ANY_ADDITIONAL_PROPERTY": {
          "location": "header",
          "schema": {
            "type": "string",
            "description": "text",
            "enum": [
              "text"
            ],
            "required": true
          },
          "required": true
        }
      },
      "agentCount": 1,
      "createdAt": "2025-12-13T09:37:34.186Z",
      "updatedAt": "2025-12-13T09:37:34.186Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 1,
    "totalPages": 1
  }
}

Create agent tool

post

Create a new custom tool for voice agents.

Tool Types

HTTP Tools - Call external APIs and webhooks:

Run on your server when the AI invokes them
Require httpMethod and baseUrlPattern
Parameters include location field (header/query/path/body)
Perfect for database lookups, external API calls, webhooks
Work across all call mediums (WebRTC, websocket, telephony)

Client Tools - Run directly in the browser:

Execute client-side JavaScript when AI invokes them
No HTTP fields required
Parameters don't use location field
Perfect for UI updates, notifications, client-side interactions
Work with WebRTC and websocket calls (not telephony)
Invoked via client_tool_invocation WebSocket messages (see /calls/create endpoint for message format)

Authorizations

X-API-KeystringRequired

API key for authentication

Body

Responses

201

Tool created successfully

application/json

400

Invalid request body

application/json

409

Tool name or model name already exists

application/json

post

/agent-tools

POST /api/v1/agent-tools HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 450

{
  "type": "http",
  "name": "Customer Lookup",
  "description": "Look up customer information by phone number",
  "modelToolName": "lookupCustomer",
  "httpMethod": "GET",
  "baseUrlPattern": "https://api.example.com/customers/{phoneNumber}",
  "automaticParameters": {
    "apiKey": {
      "location": "header",
      "knownValue": "{{API_KEY}}"
    }
  },
  "dynamicParameters": {
    "phoneNumber": {
      "location": "path",
      "schema": {
        "type": "string",
        "description": "Customer phone number to look up"
      },
      "required": true
    }
  }
}

{
  "id": "text",
  "name": "text",
  "description": "text",
  "modelToolName": "text",
  "type": "http",
  "httpMethod": "GET",
  "baseUrlPattern": "text",
  "automaticParameters": {
    "ANY_ADDITIONAL_PROPERTY": {
      "location": "header",
      "knownValue": "text"
    }
  },
  "dynamicParameters": {
    "ANY_ADDITIONAL_PROPERTY": {
      "location": "header",
      "schema": {
        "type": "string",
        "description": "text",
        "enum": [
          "text"
        ],
        "required": true
      },
      "required": true
    }
  },
  "agentCount": 1,
  "createdAt": "2025-12-13T09:37:34.186Z",
  "updatedAt": "2025-12-13T09:37:34.186Z"
}

Get agent tool

get

Retrieve a specific agent tool by ID

Authorizations

X-API-KeystringRequired

API key for authentication

Path parameters

idstringRequired

Tool ID

Responses

200

Successful response

application/json

Responseone of

404

Tool not found

application/json

get

/agent-tools/{id}

GET /api/v1/agent-tools/{id} HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "name": "text",
  "description": "text",
  "modelToolName": "text",
  "type": "http",
  "httpMethod": "GET",
  "baseUrlPattern": "text",
  "automaticParameters": {
    "ANY_ADDITIONAL_PROPERTY": {
      "location": "header",
      "knownValue": "text"
    }
  },
  "dynamicParameters": {
    "ANY_ADDITIONAL_PROPERTY": {
      "location": "header",
      "schema": {
        "type": "string",
        "description": "text",
        "enum": [
          "text"
        ],
        "required": true
      },
      "required": true
    }
  },
  "agentCount": 1,
  "createdAt": "2025-12-13T09:37:34.186Z",
  "updatedAt": "2025-12-13T09:37:34.186Z"
}

Delete agent tool

delete

Delete an agent tool (only if not assigned to any agents)

Authorizations

X-API-KeystringRequired

API key for authentication

Path parameters

idstringRequired

Tool ID

Responses

204

Tool deleted successfully

404

Tool not found

application/json

409

Tool is assigned to agents and cannot be deleted

application/json

delete

/agent-tools/{id}

DELETE /api/v1/agent-tools/{id} HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Update agent tool

patch

Update an existing agent tool

Authorizations

X-API-KeystringRequired

API key for authentication

Path parameters

idstringRequired

Tool ID

Body

anyOptional

Responses

200

Tool updated successfully

application/json

Responseone of

400

Invalid request body

application/json

404

Tool not found

application/json

409

Tool name or model name already exists

application/json

patch

/agent-tools/{id}

PATCH /api/v1/agent-tools/{id} HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*

{
  "id": "text",
  "name": "text",
  "description": "text",
  "modelToolName": "text",
  "type": "http",
  "httpMethod": "GET",
  "baseUrlPattern": "text",
  "automaticParameters": {
    "ANY_ADDITIONAL_PROPERTY": {
      "location": "header",
      "knownValue": "text"
    }
  },
  "dynamicParameters": {
    "ANY_ADDITIONAL_PROPERTY": {
      "location": "header",
      "schema": {
        "type": "string",
        "description": "text",
        "enum": [
          "text"
        ],
        "required": true
      },
      "required": true
    }
  },
  "agentCount": 1,
  "createdAt": "2025-12-13T09:37:34.186Z",
  "updatedAt": "2025-12-13T09:37:34.186Z"
}

List system tools

get

Retrieve all available system tools that can be assigned to agents

Authorizations

X-API-KeystringRequired

API key for authentication

Responses

200

Successful response

application/json

get

/agent-tools/system

GET /api/v1/agent-tools/system HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Accept: */*

200

Successful response

{
  "data": [
    {
      "id": "text",
      "toolName": "text",
      "displayName": "text",
      "description": "text",
      "createdAt": "2025-12-13T09:37:34.186Z",
      "updatedAt": "2025-12-13T09:37:34.186Z"
    }
  ],
  "total": 1
}

List agent's tools

get

Get all tools (custom and system) assigned to a specific agent

Authorizations

X-API-KeystringRequired

API key for authentication

Path parameters

idstringRequired

Agent ID

Responses

200

Successful response

application/json

404

Agent not found

application/json

get

/agents/{id}/tools

GET /api/v1/agents/{id}/tools HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "customTools": [
    {
      "id": "text",
      "name": "text",
      "description": "text",
      "modelToolName": "text",
      "type": "http",
      "httpMethod": "GET",
      "baseUrlPattern": "text",
      "automaticParameters": {
        "ANY_ADDITIONAL_PROPERTY": {
          "location": "header",
          "knownValue": "text"
        }
      },
      "dynamicParameters": {
        "ANY_ADDITIONAL_PROPERTY": {
          "location": "header",
          "schema": {
            "type": "string",
            "description": "text",
            "enum": [
              "text"
            ],
            "required": true
          },
          "required": true
        }
      },
      "agentCount": 1,
      "createdAt": "2025-12-13T09:37:34.186Z",
      "updatedAt": "2025-12-13T09:37:34.186Z"
    }
  ],
  "systemTools": [
    {
      "id": "text",
      "toolName": "text",
      "displayName": "text",
      "description": "text",
      "createdAt": "2025-12-13T09:37:34.186Z",
      "updatedAt": "2025-12-13T09:37:34.186Z"
    }
  ]
}

Assign tools to agent

post

Assign multiple tools to an agent

Authorizations

X-API-KeystringRequired

API key for authentication

Path parameters

idstringRequired

Agent ID

Body

toolIdsstring[] · min: 1Required

Array of tool IDs to assign to the agent

Responses

200

Tools assigned successfully

application/json

400

Invalid request

application/json

404

Agent or tools not found

application/json

post

/agents/{id}/tools

POST /api/v1/agents/{id}/tools HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "toolIds": [
    "text"
  ]
}

{
  "message": "text",
  "assignedCount": 1
}

Remove tool from agent

delete

Unassign a specific tool from an agent

Authorizations

X-API-KeystringRequired

API key for authentication

Path parameters

idstringRequired

Agent ID

toolIdstringRequired

Tool ID to remove

Responses

204

Tool unassigned successfully

404

Agent not found or tool not assigned to agent

application/json

delete

/agents/{id}/tools/{toolId}

DELETE /api/v1/agents/{id}/tools/{toolId} HTTP/1.1
Host: api.omnia-voice.com
X-API-Key: YOUR_API_KEY
Accept: */*

No content

PreviousPhone Numbers NextConfiguration

Last updated 3 days ago