Skip to main content
A voice agent uses regular Timbal tools. The caller asks a question, the text agent decides to call a function, and its answer is spoken back. Speech adapters do not execute the tool themselves.

Add one lookup

After the quickstart and greetings, replace agent.py with this complete example. Keep the same .env and server command:
agent.py
Restart the server and start a new session. Say “Check order 101.” You should see Calling get_delivery_status…, wait through the demo lookup, then hear that the order is shipped and expected tomorrow. An unknown ID should produce a not-found answer. These are mock records, not a live delivery integration.

What the caller hears while waiting

With the thinking sound off and no filler configured, a tool call can leave a quiet gap. This is a good baseline: first verify that the tool is called and its result is used. The next lessons add a thinking sound or a spoken filler to that gap.

Speak before a tool call

You can ask the model to say a short acknowledgement before calling a tool, such as “Let me check that…”. Timbal flushes that text to speech while the tool runs, including phrases ending in an ellipsis. The tool does not wait for synthesis to finish. The final answer follows the acknowledgement in the same turn. For a short pause between the acknowledgement and the result, set:
The default is None (disabled); 0 also disables the pause. A positive value sets the minimum silence after pre-tool playback and before post-tool synthesis. Tool execution continues during playback and the pause, so a sufficiently slow tool adds no extra wait. There is no pause before the first spoken response when the model called the tool without an acknowledgement. An enabled pause finishes the pre-tool streaming TTS context and uses a new context for the result. With the pause disabled, providers that support flushing and confirming delivery of each audio segment keep their context open across the tool call. Other providers finish the context at the boundary so interruption tracking never counts unspoken result text as heard.

Add real actions carefully

Replace the mock with an async service call when the basic flow works. For actions requiring approval, wrap the function in Tool(handler=..., requires_approval=True) and implement the approval UI and HTTP resume flow. The playground displays a pending request; it does not resolve approval from spoken words. See Approval gates and Voice approval events. A filler is an acknowledgement of waiting, not confirmation that an action succeeded. Give the final spoken confirmation only after the tool result supports it.

Report back when slow work finishes

Work that takes minutes should not hold the turn. Start it, let the call continue, and have the agent speak up when it lands. When the slow work is one of the agent’s own tools, run it in the background and turn on announce_background_results. The tool returns at once, and when it finishes the agent takes a turn of its own to tell the caller:
agent.py
When the work happens elsewhere (another service, a job queue, a browser tab), report it with session.notify(text). current_voice_session() returns the live session to a tool and to any task it starts:
Either way, the result reaches the model as a runtime message, never as something the caller said: it is not in the transcript or the captions, and it stays in memory for later turns. The agent waits for a quiet line (the caller not talking, its own audio finished, no greeting pending). If the caller speaks first, the result comes with their turn instead, ahead of what they said. Results waiting together are spoken in one turn, and a notify with the same key replaces one that has not been delivered yet. The model may decide there is nothing worth saying; then the agent stays quiet, and no filler plays. While the agent is waiting on the caller (an approval, ask_user), it does not speak up. notify() returns a receipt at once: await event.settled() reports "delivered" once a turn has it (event.run_id) or "superseded" when a newer event with the same key replaced it. Without announce_background_results, a finished background task still reaches the agent, on the caller’s next turn. A client can send events over the call’s data channel when the server allows it; see Voice transports.

Choosing what speaks up

Each tool and each event can override the call’s default with an announce policy:
  • "when_idle": take a turn once the line is quiet (the default for notify).
  • "silent": never take a turn; the result reaches the caller’s next turn. This is the default for background tools unless announce_background_results is on.
  • "interrupt": speak now. The agent cuts its own reply short, as if the caller had barged in, and what the caller already heard stays in memory. It still waits while the agent is parked on the caller (an approval, ask_user). Keep it for things that cannot wait. Events from the caller’s device cannot interrupt.

Progress while the work runs

A background tool can narrate its progress with report_progress. Each report is spoken like a notify once the line is quiet, a newer report replaces one not yet spoken, and the model is told the work is still running:
Pass announce="silent" to keep reports for the caller’s next turn instead.

Telling the client

When the agent takes a turn of its own, the client gets an event_turn_started event (task_ids, event_ids, keys, urgent) before any text or audio, so a UI can show the reply as an announcement rather than an answer. The wire metrics message is {"type": "metrics", "metrics": {...}} with metrics.event true. The same object is stored on the trace root as voice_turn_metrics. events (including announce_background_results and on_busy) is server config; a client hello cannot set it. A text turn on the same conversation while the call is live (a chat tab continuing from the call’s run) is let in only while the call is not mid-turn. While a call turn runs, the chat turn is refused, or queued with "events": {"on_busy": "enqueue"} in the server’s voice_config. Once let in, the chat turn continues from the call’s latest turn, even if the chat sent an older run as its parent, so neither side loses what the other said. A caller who speaks while the chat turn runs is answered after it, and the call continues from what the chat said. An "interrupt" event goes ahead of a queued chat turn, but waits for one that is already running.

Let the caller end the call

session.end_call() hangs up once what the agent is saying has been heard. Give it to the model as a tool, and tell it to say goodbye in the same reply:
agent.py
The session waits for the turn to finish and its audio to play, then closes itself, as session.close() does. Some models call the tool before writing the goodbye, so the tool’s result asks for one; the goodbye then comes from a second model call in the same turn, and the session still waits for it. If the caller says something first, the call stays up. If the goodbye never finishes playing, the call ends after 20 seconds anyway. Calling it again changes nothing. Continue to Thinking sounds.