How-to guidesAgents

Add tools

Create system, webhook, and client tools and attach them to an agent

Tools let the LLM act mid-call. For the three kinds and the parameter schema, see Tools.

System built-in

Add a built-in directly to the agent. builtin must be one of GET /v1/agents/tools/system-builtins; name is the identifier the LLM calls.

POST
/v1/agents/:id/builtins
1curl -X POST https://api.speechify.ai/v1/agents/id/builtins \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "builtin": "string",
6  "name": "string"
7}'
Try it

The LLM calls hang_up() and the room disconnects immediately.

transfer_to_number and play_keypad_touch_tone are SIP-dependent and return a clear error until phone-number support is enabled on your account.

Webhook tool

Create the tool. The worker signs a JSON envelope, POSTs it to your URL, and returns your response to the LLM.

POST
/v1/agents/tools
1curl -X POST https://api.speechify.ai/v1/agents/tools \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "lookup_order",
6  "description": "Fetch order details by order ID.",
7  "kind": "webhook",
8  "config": {
9    "url": "https://api.your-app.com/webhooks/lookup-order",
10    "method": "POST",
11    "timeout_ms": 5000,
12    "headers": {
13      "X-Org-ID": "acme"
14    },
15    "params": [
16      {
17        "name": "order_id",
18        "type": "string",
19        "description": "Order ID",
20        "required": true
21      }
22    ]
23  }
24}'
Try it

The create response includes the HMAC signing secret once ("webhook_secret": "wh_sec_…"). Store it now — every later read returns a masked placeholder, and there is no retrieval endpoint.

Your endpoint receives a JSON envelope and replies 200 OK with JSON, which the agent uses as the tool’s return value:

1// request body
2{ "tool_call_id": "call_abc123", "tool_name": "lookup_order", "arguments": { "order_id": "ORD-42" }, "timestamp": 1713360000000 }
3
4// your response
5{ "status": "shipped", "tracking": "1ZW…" }

Each call carries two headers:

HeaderExample
X-Speechify-Signaturesha256=<64-char hex>
X-Speechify-Timestamp1729425600000 (UNIX ms)

The signature is sha256=HEX(HMAC_SHA256(secret, "<timestamp>.<raw body>")) — sign over the timestamp, a literal ., then the raw body.

1import hmac, hashlib
2
3def verify(headers, raw_body: bytes, secret: str) -> bool:
4    ts = headers["X-Speechify-Timestamp"]
5    sig = headers["X-Speechify-Signature"]
6    expected = "sha256=" + hmac.new(
7        secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
8    ).hexdigest()
9    return hmac.compare_digest(sig, expected)

Reject deliveries more than a few minutes old to guard against replays. For method: "GET", arguments are sent as query parameters and the signature covers an envelope that isn’t on the wire — use POST for any endpoint you plan to verify.

Client tool

Runs in the caller’s browser or SDK over the session’s tools data channel.

POST
/v1/agents/tools
1curl -X POST https://api.speechify.ai/v1/agents/tools \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "navigate_to",
6  "description": "Scroll the page to a named section.",
7  "kind": "client",
8  "config": {
9    "timeout_ms": 4000,
10    "params": [
11      {
12        "name": "section",
13        "type": "string",
14        "description": "Section name",
15        "required": true,
16        "enum": [
17          "pricing",
18          "docs",
19          "contact"
20        ]
21      }
22    ]
23  }
24}'
Try it

Your client receives a tool_call and replies with a tool_response carrying the same tool_call_id on the same channel:

1// agent → client
2{ "type": "tool_call", "tool_call_id": "call_abc123", "tool_name": "navigate_to", "arguments": { "section": "pricing" } }
3
4// client → agent
5{ "type": "tool_response", "tool_call_id": "call_abc123", "result": { "ok": true } }

The @speechify/agents-js SDK will wrap this with a single registerTool(name, handler) call — the reference will be linked here when it publishes.

Attach to an agent

A webhook or client tool must be attached before the LLM can call it.

$# Attach
$curl -X POST https://api.speechify.ai/v1/agents/$AGENT_ID/tools/$TOOL_ID \
>  -H "Authorization: Bearer $SPEECHIFY_API_KEY"
$
$# Detach
$curl -X DELETE https://api.speechify.ai/v1/agents/$AGENT_ID/tools/$TOOL_ID \
>  -H "Authorization: Bearer $SPEECHIFY_API_KEY"
$
$# List attached
$curl https://api.speechify.ai/v1/agents/$AGENT_ID/tools \
>  -H "Authorization: Bearer $SPEECHIFY_API_KEY"