The call brief
voice_engine.brief() builds one document per call — the persona, the line's purpose, the contact's facts and standing instructions, knowledge, the hard rules and any supervisor guidance — and hands it to the model once. Its size is recorded as session.instructions_chars, because size is measurably latency: 7,500 characters gave a 1.2–1.8 second first token and 9,600 gave 2.3–3.4.
One document, built once, in one place#
The voice worker carries audio and posts events. It holds no business logic, knows no rules and looks nothing up. Everything it needs is rendered by the engine before the call and delivered as instructions, which is what makes the same behaviour reachable from the carrier path, the realtime path and a test call in the Lab without three implementations of it.
- Persona — who the voice is, including a human voice profile if one is assigned.
- The line's purpose — inbound, service, transactional or promotional. There is no campaign object; purpose is the axis.
- Contact facts and standing instructions — what is known about this person and what somebody has told Connect to do about them.
- Knowledge — grounding drawn from the workspace's own sources.
- The language rule — two or three lines written by
voice_region.planfrom what is known about this caller: which language to reply in, what evidence moves it, and how to sound like a courteous local professional when it is not English. - The hard rules — the boundaries that do not bend, including what must never be said.
- Supervisor guidance — anything a colleague has already added for this call.
The behaviour texts around those — role, goal, tone, style, what to ask and never ask, objections, escalation, opening, closing, proactiveness, switching, memory use — come from the Voice Lab's behaviour_block, and the speaking directions from style_block.
The budgets#
| Part | Budget |
|---|---|
| Knowledge | 4 facts / 2,000 characters |
| Memory | 700 characters |
| Contact block | 600 characters |
| Human voice profile block | under about 2,500 characters |
These are not style guidance. Instruction size is on the record for every session precisely so the relationship between size and first token stays visible, and the two measured points — 1.2–1.8 s at 7,500 characters, 2.3–3.4 s at 9,600 — are what the budgets were set against. A caller pays that difference on every single reply.
Changing something mid-call#
The brief is rendered once, so anything added later has to travel another way, and there are two with very different costs.
agent.update_chat_ctx- A user-role turn taken without generating a reply. Small, cheap, and how a steering note, a read-back note and the 12-turn anchor note all arrive.
update_instructions- Resends the whole prompt. Kept for supervisor guidance only, because re-sending several thousand characters mid-call is exactly the cost the budgets exist to control.
On Gemini 3.1 Flash Live neither is available: the SDK marks the session immutable, notes come back undelivered and guidance is recorded as guidance_undeliverable. On that model the brief is the whole conversation's instruction set, which raises the stakes on getting it right before the call rather than steering during it.
What the brief is not#
- It is not a transcript store. What has been said accumulates in the session's context, and that context is re-billed on every turn — production calls run at about 92% carried context by input token.
- It is not a retrieval loop. Knowledge is selected before the call, not fetched mid-sentence, which is why the four-fact cap is a real constraint rather than a first page of results.
- It is not where the greeting lives. That is deterministic text, pre-synthesised as audio; the instructions merely say the opening has already been spoken.
This page was reconciled on 2026-09-10 against backend/app/voice_region.plan at f5ea518. The structure, the budgets and the delivery mechanisms are unchanged. The contact-facing language lines are the part that moved: they now carry a different evidence bar depending on what is known — nothing moves a pinned call, a whole sentence moves a remembered or unknown one, and two or three words move one where the contact's city or state made a language likely. Nothing in the brief offers a language or quotes a sample phrase, because on a production call an earlier brief's sample was read out to the caller word for word.
Questions#
Can I see the brief that was used on a particular call?
Its size is recorded per session as instructions_chars, and the resolved voice settings are snapshotted on call.quality so the review judges what actually ran. Those two together answer most questions about why a given call behaved as it did.
Why cap knowledge at four facts when the workspace has hundreds?
Because they would all be paid for on every reply, and because a model given twenty facts about a subject answers less precisely than one given the four that matter. The cap forces the selection to be good rather than generous.
Is the brief different for the Owner and for a customer workspace?
No. It is one renderer with two routes into it, which is the general shape of the phone system — the seam is one body and two doors, not two implementations that have to be kept in step.