- Build does the whole job in one call — it writes the prompt, simulates test calls against it, judges them, and fixes what breaks. You don’t wire those steps yourself.
- Poll because a build takes a couple of minutes to finish.
- Read the record if you want to peek at how the test transcripts came out.
- Simulate more conversations, optionally — your own personas, your own objections.
- Change the assistant directly via the update API or the portal — or through refine. Refine is not recommended when you’re almost there: it reconsiders the whole prompt, and like all LLM work, that can be unstable.
What a build does
One request kicks off the whole thing. An author writes the prompt from your brief. About ten test callers rehearse it in parallel: the busy one, the suspicious one, the one who tries to jailbreak it. A judge reviews every transcript, and the prompt gets rewritten against the findings. Up to a few rounds, until the findings hit zero or the rounds run out. It takes minutes, and it survives your refresh: theassistantId exists from the first response.
Poll every few seconds. The phase tells you where it is:
Writing the brief
context is free text, but the briefs that build best read as labelled lines:
context brief. If there are extra variables or attributes unique to each caller, specify them in the brief, example:
POST /realtime-assistants/builds
sampleRows (send two or three real rows) serve two purposes: they ground the test callers in real customers, and they’re injected into rehearsals exactly the way production hands the agent a record per call. Use the same keys you’ll send as variables on real calls — the prompt’s {tokens} are written against them. And name your columns like a human: Amount, DueDate, AppointmentTime — never Detail 1.
Done is not passed
The status poll’sdone means the pipeline stopped. result.passed tells you whether the judge was satisfied. passed: false still saves a callable assistant. It just means the rounds ran out with findings open. When that happens, read the chosen negative transcript in the build record and find the ugly moment. A small flaw — one line, one phrase — is a direct edit to the prompt. A broader miss is worth a refine.
The record also has the two sample transcripts worth reading first: the cleanest happy call and the cleanest difficult one, with Roman transliteration alongside the Urdu.
Simulate your own callers
The build already rehearsed the standard cast — the busy one, the suspicious one, the jailbreaker. Use simulate for the callers only you know: your objections, your pricing pushback, the caller who names your competitor. Describe the persona by how they act, not an adjective: “interrupts early, demands to know where you got the number, hangs up if the answer is vague.” One gotcha: omitvariables and the test caller gets your brief’s first sample row, not a blank slate (an assistant with no build brief does get the blank slate).
Refine vs edit
Most changes don’t need a refine. A knob (voice, model, tools) or a small prompt fix — a line you’d reword, an opener you’d tighten — is a direct edit via the update API or the portal. Refine is for real rework of what the agent says. It reruns the whole rehearse-and-grade loop (same minutes as a build), regenerates the config from the brief so hand-edits to voice or tools don’t survive it, and like any LLM pass, the result can shift in ways you didn’t ask for. When you do refine, critique like you’d brief a copywriter: name the phrase, the word, the line that’s off. “Still not right” burns a real build and fixes nothing.ownerFeedback in Urdu works — write it in the language you want acted on. And one refine at a time: a second one while the first runs comes back as failed in the poll.