Add one lookup
After the quickstart and greetings, replaceagent.py with this complete example. Keep the same .env and server command:
agent.py
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: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 inTool(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 onannounce_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
session.notify(text). current_voice_session() returns the live session to a tool and to any task it starts:
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 fornotify)."silent": never take a turn; the result reaches the caller’s next turn. This is the default for background tools unlessannounce_background_resultsis 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 withreport_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:
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 anevent_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
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.