Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
[This article is prerelease documentation and is subject to change.]
An agent that looks correct in the Build tab can still fail in conversation. Instructions are guidance, not guarantees: the model interprets them, and the gap between what you wrote and what the agent does only shows up when you actually talk to it. Use the Preview tab to test your agent across both web chat and voice before you publish it.
Test channels
The Preview tab provides two ways to test your agent:
- Web Chat: A text-based chat pane. This is where you should spend most of your testing time. It's faster than voice, the full transcript is visible, and you get a reasoning trace alongside the chat.
- Voice Call: A live voice conversation with your agent. Voice has failure modes that text never surfaces, so test it separately even when chat passes cleanly.
Select Web Chat or Voice Call at the top of the Preview tab to switch between test channels. A Live Transcript panel appears alongside the conversation.
Before you start
- Save your changes. The Preview pane runs your saved agent, not unsaved edits in the Build tab.
- Know what "correct" looks like. Write down the expected outcome before you send the first message.
- Open the Activity map. It sits beside the chat and shows routing, tool calls, and topic execution. It's how you tell a reasoning failure from a plumbing failure.
- Start a new test session between scenarios. Context carries over and will contaminate your next result.
The five layers to test
Work outward from the simplest layer. A failure in an early layer will cascade, so fix issues in order.
| Layer | What you're testing | How to tell it works |
|---|---|---|
| Greeting and scope | The agent introduces itself and understands its own job | Opening message matches your description; it accepts in-scope asks |
| Routing | The orchestrator picks the right sub-agent | Activity map shows the expected specialist invoked |
| Tools and topics | Actions actually execute and return data | Real values come back, not placeholders or silence |
| Knowledge | Answers are grounded in your sources | Citations appear and match your configured sources |
| Guardrails | Refusals, escalation, and business rules hold | The agent declines, escalates, or flags exactly as instructed |
Testing in web chat
Run the happy path first
Play a realistic user with a complete goal, not a tester poking at features. For example, for a travel agent, that means booking an actual trip end to end rather than asking "can you book flights?"
- Open the goal naturally, the way a real user would.
- Answer the agent's questions as a cooperative user.
- Follow the flow to a real conclusion: a booking, a summary, a resolution.
- Ask for a recap at the end, then verify every fact in it against the transcript.
Then break it on purpose
The happy path proves the agent can work. These scenarios prove it fails safely.
| Test | What to send | What should happen |
|---|---|---|
| Missing detail | Skip a required field the agent needs | It asks for exactly that field, once |
| Change of mind | Reverse a decision mid-flow | It updates without losing earlier context |
| Out of scope | Ask something outside its domain | It declines and redirects, without improvising |
| Escalation | Trigger a documented handoff rule | It transfers instead of attempting the task |
| Business rule | Violate a stated limit, such as budget | It flags the conflict explicitly |
| In-session memory | Ask it to repeat a detail from earlier | It recalls accurately, without re-asking |
Read the Activity map, not just the reply
The chat tells you what the agent said. The Activity map tells you what it did. When a response looks wrong, the map tells you where to fix it:
- Wrong specialist invoked → your routing instructions or sub-agent descriptions are ambiguous.
- Right specialist, bad output → the sub-agent's own instructions need work.
- Tool ran but returned nothing → the tool or topic is broken, not the prompt.
- No tool call at all → the agent answered from the model instead of your data. Treat every value in that reply as unverified.
Testing in voice
Voice is not web chat with audio attached. It has failure modes text will never surface, so test it separately even when chat passes cleanly.
- Grant microphone access, then start the voice conversation and confirm the status reaches a connected, listening state.
- Speak a full request naturally instead of reading a script word by word.
- Watch the live transcript. If speech recognition mis-hears you, the agent's reply is answering a different question than the one you asked.
- Interrupt the agent mid-sentence to verify barge-in stops playback and listens.
- Stay silent for several seconds to confirm it re-prompts politely instead of dropping the call.
- Ask for a confirmation code and check that it's spelled out character by character, not read as a word.
What to listen for
- Length: Anything over about three sentences is too long to follow by ear.
- Lists and URLs: These must be summarized, never read aloud item by item.
- Dates and numbers: "Tuesday, March twenty-fourth" works; "2026-03-24" does not.
- Confirmation of critical data: Names, dates, and codes should be repeated back before the agent acts on them.
If Speech behaves like your Chat channel, your channel-specific instructions aren't doing their job. Speech and Chat instructions are configured separately on each agent, in the Instructions section's Speech and Chat tabs. See Speech and chat settings overview.
Tip
Run your critical scenarios more than once, and run at least one long session. Intermittent failures are still failures, and they're the ones that reach production.
When something fails
- Reproduce it. Start a new session and run the same path again, noting whether it fails every time or intermittently.
- Locate it using the Activity map: routing, tool, knowledge, or instruction.
- Fix one thing at a time. Changing several instructions at once makes it impossible to tell what worked.
- Save, start a new session, and re-run the exact same scenario.
- Re-run your other passing scenarios. Instruction changes have side effects.
Ready-to-ship checklist
- The happy path completes end to end without hand-holding.
- Every fact in the final summary is traceable to something a tool or knowledge source actually returned.
- No placeholder text appears anywhere in a user-visible response.
- The agent reports failure honestly when a tool returns nothing.
- Escalation and refusal rules fire reliably.
- Voice responses are short, and codes are spelled out.
- Critical scenarios were run more than once, including one long session.