A caller asks your agent to move an appointment. The model picks the right tool, fires the call, and goes silent for three seconds while your calendar API thinks. The caller repeats themselves. The model, now hearing new input, cancels the pending tool call and tries to reinterpret the request. You have a broken turn, a confused caller, and a support ticket by the end of the day.
The fix is a preamble: a short spoken acknowledgment before or during a tool call. OpenAI shipped preambles as a first-class primitive in GPT-Realtime-2, and their prompting guide now makes them the default recommendation for any turn that involves reasoning or a tool call. That is a big deal, and it also means "does the preamble work" is now a testable behavior your QA harness has to cover. Below is how to think about that.
What a preamble actually is
A preamble is a short, spoken acknowledgment that the agent produces before a longer response, typically before or during a tool call. OpenAI's own examples are the ones every builder has now seen a dozen times: "let me check that", "one moment while I look into it". The Realtime 2 prompting guide is explicit that preambles are short spoken updates, not hidden chain-of-thought, and that the model should describe the action rather than its internal reasoning.
A preamble is not a filler word. It is a specific piece of output with a job:
- Close the perceived-latency gap so the caller does not think the line dropped.
- Signal to the caller which action is about to happen, so barge-in has a target.
- Give the tool call cover to complete without the caller talking over it.
Preambles are also not the same thing as an async status update. Preambles land in the same turn as the tool call. Async status updates are for the long-tail case where a write takes so long you should give a receipt and finish in a follow-up call or callback. Both matter. Only preambles are on the critical path for every turn.
Why preambles need testing, not just prompting
The temptation is to write "always speak a brief acknowledgment before calling a tool" into your system prompt, run one happy-path call, and call it done. That does not survive contact with real callers, for six reasons.
Timing. Preambles are latency-sensitive. If the preamble fires 2 seconds after the tool call starts, it does not cover the silence, it just arrives inside it. The Realtime API docs note that preambles reduce perceived latency, but only if they precede the wait, not chase it. You need a metric on time-from-tool-decision-to-first-preamble-audio, and you need to test at realistic network conditions.
Semantic mismatch. The model can produce "let me check your calendar" while actually calling a CRM lookup, or announce the wrong entity ("checking your Tuesday appointment" for a Wednesday query). This gets worse as tool inventories grow. Preamble text and tool identity have to agree.
Over-eagerness. Realtime models will happily preamble every turn if you tell them to acknowledge tools. That produces a call where the agent says "one moment" three times before it says anything useful. Agora's early-testing writeup on Realtime 2 puts the rule plainly: no preamble for simple turns, one short preamble for longer reasoning or tool-calling turns.
Barge-in behavior. Preambles are short, but they are still speech. The model has to yield if the caller starts talking, cancel the tool call cleanly, and reinterpret. Otherwise the preamble becomes a way to trap a caller who is trying to correct you.
Tool failures. The preamble commits the model to an action ("let me pull that up"). If the tool errors, the recovery has to either retry silently or verbalize the failure. Silent success followed by silent failure is worse than no preamble at all.
Parallel tools. GPT-Realtime-2 supports parallel tool calls, which is great for latency and terrible for preamble discipline. The model will sometimes stack preambles ("let me check that... one moment... just a second") or preamble one of the two calls and leave the other silent.
Each of these is a distinct failure mode. Each one deserves at least one scenario in a test suite.
Six preamble tests worth running
Here is a starter set. Every scenario below runs the agent over a real audio channel, dialed as a phone call, with a caller persona that behaves specifically to trigger the case. That last part matters: preamble bugs are timing bugs, so a text-loopback harness will silently pass everything.
1. Fast-read: no preamble expected.The caller asks something the agent can answer from cache or the model's own knowledge, with no tool call. The agent should not preamble. A model that says "let me check that" and then answers instantly sounds anxious and makes every subsequent preamble less credible.
2. Slow tool call: preamble fires before the wait.The caller triggers a tool with an artificially injected 1.5 to 3 second delay. The preamble must land before the first 800 milliseconds of silence, and must precede the tool round-trip, not overlap the end of it.
3. Preamble entity matches tool.The caller asks about "my Wednesday appointment" and the agent calls the scheduling tool. The preamble text has to reference scheduling or the appointment, not "let me check your account" or "pulling up your policy". A cheap check: run a scored metric that compares the tool name and arguments against the preamble transcript.
4. Preamble survives barge-in.The caller starts talking 200 milliseconds into the preamble. The agent should yield within one turn boundary, cancel the pending tool call, and reinterpret. A common regression: the model completes the preamble regardless, then fires the tool anyway, then has to explain a stale result.
5. Preamble plus tool error.The tool call fails or times out after the preamble has been spoken. The agent has committed to "let me pull that up". It now needs to say something. Test that it retries once or reports the failure verbally within a bounded time. Silence after a preamble is the worst outcome.
6. Parallel tools without preamble stacking.The caller triggers a turn that legitimately needs two tool calls in parallel, for example a calendar check and a CRM update. The agent should preamble once, not twice, and should not fire a second preamble mid-execution.
What audio-native metrics catch that transcripts miss
A transcript will show that "let me check that" was said. It will not tell you whether it was said 200 milliseconds too late, whether the model overlapped the caller mid-preamble, or whether the pause after the preamble was too long because the tool call did not actually start until the utterance finished. Those are audio problems.
Preamble tests need at least these signals:
- Time to first preamble audio from the tool-decision boundary. This is the number that decides whether the preamble did its job.
- Dead-air distribution across the turn, before and after the preamble. Sum of dead-air windows above 800 milliseconds is a better score than a single average.
- Overlap detection. Did the model speak while the caller was speaking? Preamble-triggered barge-in failures often show up here first.
- Preamble-to-tool semantic agreement. A cheap LLM-graded metric that flags "the preamble described a lookup but the tool call performed a write".
- Prosody. Preambles are supposed to sound natural. A model that reads "let me check that" as if it were narrating a legal disclosure will make callers hang up faster than the silence would have.
If you are staring at a transcript viewer to grade this, you will miss half of it. Grade the audio.
Regression testing when the model rolls
Preamble behavior is model-dependent. It changed noticeably between original gpt-realtime and gpt-realtime-2, and OpenAI's own prompting guide is explicit that Realtime 2 should be prompted "as a reasoning voice agent, not as a basic voice bot", with different defaults for reasoning effort and preamble behavior. Any time your provider ships an updated model, a preamble suite is one of the first regressions to hit.
The same is true for prompt changes. Reword the system prompt to be more concise and you can accidentally drop the preamble guidance, or tighten it so much the model preambles on every turn. Running the six scenarios above on every prompt change is cheap and it catches this.
The pattern that works: keep the preamble suite in CI, gated on a real phone or WebRTC channel, and re-run on every model swap, every prompt edit, and every deploy. Then replay a rolling window of real production calls that touched a tool, scored against the same metric set, so you catch drift the synthetic suite never anticipated. This is the exact loop Roark is built for. Simulations dial your agent over real telephony to run the preamble suite before launch, and production call replay turns any failed live call, including the ones where the preamble was late by half a second, into a repeatable regression test on the next model version.
What to write into the system prompt anyway
Testing does not replace prompting. It grades it. The Realtime 2 prompting guide gives a reasonable starting point: describe the action, not the reasoning; vary wording across turns; keep preambles natural and concise; avoid filler. A prompt that says "always speak a preamble before calling any tool" will over-fire. A prompt that says "speak a short acknowledgment when a tool call is expected to take more than 500 milliseconds, describing the action" is testable, tunable, and aligns with how the model actually behaves.
Then run the suite. The gap between "the prompt says preamble" and "the caller heard a preamble on the turn that mattered" is where most preamble bugs live, and the only way to close it is to score the audio on every deploy.
