Omni function calling (tools)

​

Hosted catalog (zero setup)

​

Catalog at a glance

​

Live hosted tools, arguments & results

// result
{
  "query": "what is the refund policy?",
  "passages": ["Returns are accepted within 30 days …"],
  "results": [{ "kb_id": "kb_…", "document_id": "doc_…", "content": "…", "score": 0.82 }]
}

{ "expression": "2 + 3 * 4", "value": 14 }

{ "timezone": "America/New_York", "iso": "2026-06-23T01:42:00.000Z", "unix": 1782157320, "local": "Monday, June 22, 2026 at 9:12:00 PM EDT" }

{ "value": 10, "from": "km", "to": "mi", "result": 6.21371 }

{ "amount": 10, "from": "USD", "to": "EUR", "rate": 0.92, "result": 9.2 }

{
  "location": "Berlin, Germany", "units": "°C",
  "current": { "temperature": 21, "humidity": 55, "wind_speed": 12, "conditions": "partly cloudy" },
  "forecast": [{ "date": "2026-06-23", "high": 24, "low": 14, "conditions": "overcast" }]
}

{ "query": "Paris", "results": [{ "name": "Paris", "latitude": 48.85, "longitude": 2.35, "country": "France", "region": "Île-de-France" }] }

{ "query": "voice ai", "source": "wikipedia", "results": [{ "title": "Voice AI", "description": "…", "excerpt": "…", "url": "https://en.wikipedia.org/wiki/Voice_AI" }] }

{ "topic": "electric vehicles", "articles": [{ "title": "…", "link": "https://…", "published": "Mon, 23 Jun 2026 …" }] }

​

Tool settings (per-agent config)

// GET /v1/tools  → the send_sms catalog entry
{
  "name": "send_sms",
  "execution": "hosted",
  "side_effect": "action",
  "config_schema": {
    "fields": [
      { "key": "from_number", "label": "From number", "type": "string", "required": true },
      { "key": "provider_api_key", "label": "Provider API key", "type": "string", "required": true, "secret": true }
    ]
  }
}

curl -sS -X PUT https://api.pyai.com/v1/agents/$AGENT_ID/tools \
  -H "Authorization: Bearer $PYAI_API_KEY" -H "Content-Type: application/json" \
  -d '[{ "tool_id": "tool_send_sms", "enabled": true,
         "config": { "from_number": "+15551234567", "provider_api_key": "sk_live_…" } }]'

​

Server mode (PyAI calls your webhook)

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 by id",
    "input_schema": { "type": "object", "properties": { "order_id": { "type": "string" } }, "required": ["order_id"] },
    "webhook_url": "https://api.yourapp.com/pyai/tools/order",
    "execution": "server",
    "side_effect": "read",
    "timeout_ms": 5000
  }'

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 }]'

​

What PyAI sends your webhook

{
  "call_id": "call_abc123",
  "tool": "get_order_status",
  "org_id": "org_…",
  "agent_id": "support-bot",
  "arguments": { "order_id": "A-1001" }
}

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const [tPart, vPart] = header.split(",");
  const t = tPart.slice(2);          // strip "t="
  const sig = vPart.slice(3);        // strip "v1="
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay window
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, sig = parts["t"], parts["v1"]
    if abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

​

What your webhook should return

{ "status": "shipped", "eta": "Tuesday", "tracking": "1Z…" }

​

Reliability you get for free

• Soft-fail, a timeout, 5xx, or unreachable webhook becomes a structured error the agent can apologize for; it never crashes the call.
• Timeouts & size cap, the effective budget is min(timeout_ms, platform ceiling); the ceiling is 5 s by default, so registering timeout_ms above it has no effect unless PyAI raises the ceiling for your org. Results larger than ~6 KB are truncated.
• Idempotency, a retried voice turn reuses the same call_id; PyAI replays the prior successful result instead of calling your webhook again, so an action tool (charge a card, send a text) fires once. Still, treat call_id as an idempotency key on your side.
• Circuit breaker, if your webhook fails repeatedly, PyAI briefly stops calling it (and tells the agent the tool is unavailable) instead of hammering a broken endpoint and slowing every turn.
• SSRF-safe, only the exact webhook_url you registered is ever called, and only over public HTTPS (private/loopback/metadata addresses are rejected).

​

Engine mode (call control)

• PyAI managed Telephony (beta), buy a number, bind it to an agent, and PyAI runs the bridge. Managed call control is coming soon: PyAI’s bridge will perform these verbs for you (and fold the agent’s destination setting into transfer_to_human), so they work end-to-end with no transport code.
• Your own transport, you connect the WebSocket and translate each frame into a carrier operation (the Twilio and FreeSWITCH guides show working handlers).

​

Client mode (on the WebSocket)

​

Side effects & confirmation

​

See also