Functions: give your agent tools to call
Let a voice agent invoke your APIs mid-call — book a meeting, look up an order, transfer to a human. The function-calling protocol, parameter schemas, and the patterns that keep latency low.
Updated May 6, 2026
Functions are how a voice agent does anything beyond talking — book a meeting, look up an order, fire a webhook, transfer to a human. You define the tool; the LLM decides when to call it; the platform handles the I/O.
The mental model
A function is just an HTTP endpoint plus a JSON Schema describing its parameters. The LLM reads the schema, the user's intent, and decides when calling makes sense:
Caller: "What's the status of order 4521?"
LLM: decides to call get_order_status({"order_id": "4521"})
Platform: POSTs to https://your-api.com/order-status with the args
Your API: returns {"status": "shipped", "eta": "2026-05-08"}
Platform: hands the result back to the LLM
LLM: "Your order is shipped, expected to arrive May 8."
The agent narrates a filler line ("let me check that for you") while the HTTP call is in flight, so the silence doesn't feel like a hang.
Defining a function
curl -X POST https://api.call2me.app/v1/agents/agent_abc123/functions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "get_order_status",
"description": "Look up the shipping status of an e-commerce order by ID.",
"url": "https://your-api.com/order-status",
"method": "POST",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The order number, digits only"
}
},
"required": ["order_id"]
},
"speak_during_execution": "Let me check that for you...",
"timeout_ms": 4000
}'
Or in the dashboard: Agents → Edit → Functions → New Function.
What each field does
| Field | Purpose |
|---|---|
name | Internal identifier; what the LLM uses to call it |
description | The LLM reads this to decide when to call. Be explicit. |
url | Your endpoint (HTTPS only) |
method | GET, POST, PATCH, or DELETE |
parameters | JSON Schema — the LLM will fill these from the conversation |
speak_during_execution | What the agent says while waiting for your response |
timeout_ms | Max wait before the platform gives up (default 5000) |
What your endpoint receives
POST https://your-api.com/order-status
Content-Type: application/json
X-Call2Me-Call-Id: call_xyz789
X-Call2Me-Agent-Id: agent_abc123
{
"order_id": "4521"
}
Your endpoint returns a JSON object. Whatever you return becomes available to the LLM:
{
"status": "shipped",
"carrier": "UPS",
"tracking_number": "1Z999AA10123456784",
"eta": "2026-05-08"
}
The LLM reads the result, summarizes it for the caller, and continues the conversation.
Built-in functions
Some functions are provided by the platform and don't require an endpoint:
| Function | What it does |
|---|---|
transfer_call | Hand the active call off to a phone number |
end_call | Politely end the call |
send_sms | Send an SMS to the caller mid-call (if SMS is enabled on the number) |
Configure these from the same Functions panel — same schema, no url
needed.
Latency budget
Phone conversations are unforgiving. Aim for:
- < 500ms — feels instant, no filler needed
- 500ms–1.5s — the
speak_during_executionfiller bridges it cleanly - 1.5s–4s — feels slow; consider a longer filler with confidence
- > 4s — fix the underlying API or pre-fetch ahead of the call
For inbound calls where you know the caller's identity from the number,
pre-fetch their data into dynamic_variables instead of calling
mid-conversation.
Error handling
When your endpoint times out, errors, or returns non-2xx, the platform sends a synthetic error result back to the LLM:
{ "error": "request_failed", "detail": "Endpoint returned 503" }
Your agent prompt should know what to do:
"If a function call fails, apologize briefly and offer to transfer the caller to a human."
This is the pattern that keeps a single backend hiccup from torpedoing the conversation.
What's next
Frequently asked
Q.What's a function in voice AI?
A callable tool the agent can invoke during a conversation. You define name, description, and JSON Schema parameters; the LLM decides when to call it; the platform executes the HTTP call to your endpoint and returns the result back into the conversation.
Q.How fast does a function call have to return?
Under 500ms is ideal — the agent says a brief filler ('let me check that') while the call is in flight. Above 1.5s you'll start to feel awkward pauses. Plan for the slowest realistic case and design the agent's prompt to bridge the gap.
Q.Can a function transfer the call to a human?
Yes. The transfer_call function is built in — pass it a phone number and the platform routes the active call. You don't have to implement the carrier side; the platform handles SIP REFER or carrier-specific transfer.
Q.What if my function endpoint fails?
The platform surfaces the error to the LLM as the function result. Your agent prompt should tell the model what to do on failure — usually 'apologize and offer to transfer to a human' or 'try again once.'