Skip to main content
Omni agents can call functions during a live call — look up an order, book an appointment, check inventory — without leaving the voice session. Two modes, one tools[] array:
ModeWhenHow it runs
Client-loop (default)Browser apps, telephony bridges, anything already running your code on the WSEngine → tool_call frame; you → tool_result on the same socket
Engine-POST (optional)Thin clients with a public HTTPS backendSet endpoint on the tool; engine POSTs arguments to your URL
Client-loop is live today. Engine-POST follows the same pattern as kb_endpoint and is rolling out for registered webhook tools.

​
Quick start (client-loop)

  1. Open an Omni session (omni:session scope):
wss://api.pyai.com/v1/omni?format=pcm16&rate=24000
  1. Send a configure frame with tools[] (see the wire protocol).
  2. Handle tool_call → reply with tool_result.
Test without a key using the offline omni-mock example.

​
Register webhook tools (optional)

For engine-POST or reusable tool definitions bound to agent profiles: 
curl -sS https://api.pyai.com/v1/tools \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_order_status",
    "description": "Look up an order",
    "input_schema": { "type": "object", "properties": { "order_id": { "type": "string" } } },
    "webhook_url": "https://example.com/pyai/tools/order",
    "timeout_ms": 5000
  }'
Save the returned hmac_secret — it is shown once and verifies signed delivery from PyAI. Bind tools to an agent profile: 
curl -sS -X PUT "https://api.pyai.com/v1/agents/agent_…/tools" \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{ "tool_id": "tool_…", "enabled": true }]'

​
Timeouts & errors

Tools are load-bearing — the agent’s answer depends on the result. Unlike kb_endpoint grounding (300 ms, fail-open), tools use a ~5 s default budget. On timeout the engine injects a structured error so the agent can apologize; results over ~6 KB are truncated.

​
See also

Omni wire protocol

Full frame reference including tool_call / tool_result.

Browser voice agent

End-to-end website agent with grounding.

API reference

/v1/tools and /v1/agents/{id}/tools.

Offline mock server

Build your client before you have a key.