Playground and Interactive Testing
Test agents interactively in the Developer Console playground through voice or text, with optional inspection panels and related testing workflows.
Use the Playground to try a configured service and inspect its response, tool activity, and state transitions. Start with First Console Conversation for the step-by-step text walkthrough, including workspace access, service readiness, and cleanup.
This page explains the available modes and how interactive testing relates to tool tests, timelines, and simulations. Use simulations for repeatable pre-deployment evidence.
Playground Modes
Open Evaluate > Playground in the Developer Console. It exposes the modes supported by an eligible active service:
Voice - a browser-based voice call with live audio
Text - a turn-by-turn text conversation
Voice services can expose both modes. Text services expose text mode only. The Console presents one text mode using conversation API operations and background-delivery events.
Text sessions start manually: you optionally set a caller phone number or entity ID, choose whether the user or the agent speaks first, and start the session when ready. In user-first mode (the default), the session waits for your opening message. In agent-first mode, the agent generates the opening message immediately after the session starts. The entity ID input accepts a UUID or phone number and flags invalid formats before the session can start.
When the service declares accepted_context, text mode's session options include a Conversation context field for each declared key, labeled with its type, whether it is required, and its description. The Console checks the values before the session starts: required fields must be filled, number fields must be finite numbers, string values are limited to 8,192 characters, and no more than 50 values can be supplied. The values are sent as the context map on the conversation-create request. A service with no declared keys shows a note pointing to the service API instead of fields. See Pass Context to Tool Parameters for the service schema and binding setup.
Text mode can toggle the Context Graph and Timeline panels through keyboard shortcuts or toolbar buttons. Voice mode has its own observer-driven inspection layout. See Text Sessions for the underlying REST/SSE contract.
Live Inspection
Text mode displays conversation responses and available persisted turn details, supplemented by live background-delivery events. Voice mode uses its live observer connection. The inline trace shows observed tool execution and duration; it does not expose hidden model reasoning, and event completeness depends on the session path and available evidence.
When a background skill or deferred tool completes during a connected session, supported delivery events can add the result and a follow-up message to the timeline. Conversation scoping and idempotency controls reduce stale or duplicate delivery, while the UI surfaces known turn failures in an error state.
Approval Gates in the Playground
When an integration write is parked for approval during a text playground conversation, the UI can show an approval card with Approve and Reject controls. The decision is stored independently of the streaming connection and is consumed by the conversation on a later turn. Tool-call logs record the observed execution result; do not rely on model narration alone as proof that an approved external write completed. See Approval-Gated Integration Writes for the full contract.
Caller Identity
Open Configure session options, the arrow beside the start button. Voice mode exposes Caller ID; text mode exposes Entity ID, which accepts a UUID or phone number. Use an agreed synthetic identity when testing caller-specific context. The value is remembered per mode, so inspect it before starting a new test.
Leaving the field blank omits that explicit identity from the start request. It does not remove data or tools already available to the service. Use a service configured for context-free testing when no patient context is intended.
Agent Forge supports caller context on tracked simulation sessions: session-create and smoke-test accept --caller-id for an E.164 phone number, while session-create and bridge accept --entity-id for direct entity binding. The bridge command does not accept --caller-id. Omit the supported context flags to simulate an unknown caller. See Agent Forge CLI for usage.
Channel-Appropriate Output
Text playground and simulation sessions automatically use the web channel profile, so the agent omits voice-specific markup (such as TTS pronunciation hints and vocal annotations) that would otherwise appear as literal text in the chat interface. Voice playground sessions use a separate connection path and apply the voice channel profile. You do not need to configure this - the platform selects the correct profile based on which playground or simulation path you use.
Promoting a Session for Deeper Analysis
The current text Playground creates durable conversations. To carry an interesting exchange into repeatable evaluation, record the service configuration, input, expected result, and observed answer, then create the corresponding case in your simulation workflow.
Coverage session promotion belongs to the separately supported simulation APIs. Do not pass a text conversation ID to an API that expects a coverage session ID; see Simulation Coverage.
Branch Explorer
The current text Playground does not expose a Branch Explorer control. To compare alternative caller phrasings, run separate tests with the same reviewed configuration and starting context, or use the supported simulation coverage and forking workflow. A new text conversation is a new test, not a fork of an earlier turn.
Tool Testing
The standalone /tools/execute test path runs world tools outside a conversation. Skills, integration endpoints, platform functions, and workspace data queries use their own test or invoke endpoints, each with separate authorization and side-effect semantics.
World-tool tests read the live workspace context. Treat them as real operations unless the specific path documents otherwise:
World-event source tag - Supported world writer handlers persist with
source=tool_test. That source is excluded from entity projection, production analytics, billing, and outbound sync, but the event write itself still occurs.Dry run - For supported world writer handlers,
dry_run=truereturns a simulated result without persisting the write. Verify support for the tool you are testing.Other tool families - Skill and integration test endpoints can call models or external systems. Use test credentials, non-production records, and vendor sandbox environments where available.
The world-tool resolver returns the service bindings, available schema metadata, tier, and write classification. Execution returns the observed result, duration, source, dry-run flag, and any reported blocked effects or error. Empty metadata fields do not imply that an unknown tool is safe to execute.
Simulation-tagged events can contribute to visible entity state while remaining excluded from production analytical pipelines. Text Playground conversations use the ordinary conversation API, so do not assume the same exclusions from the Console entry point alone. Confirm the source and traffic classification described under Test Traffic and Billing.
Tool testing answers the question: does this tool do what I expect with this input?
Test Call Error Reporting
When a test call cannot start because of a configuration problem - such as a missing agent version, an unpublished context graph, or a service that does not exist - the platform rejects the connection with a typed error code and a human-readable explanation. This gives developers immediate feedback about what to fix instead of silently starting a degraded session. Error codes are stable identifiers that frontends can use to display targeted banners or dialogs. Production calls are not affected by this behavior.
Call and Turn Timelines
The call-detail API exposes a typed playback timeline and a timeline-only endpoint. When timing evidence exists, segments can be grouped into caller, agent, operator, tool, and system lanes. Older, partial, or unsupported records can return an empty timeline or estimated offsets, so consumers must handle missing precision.
In the console, the multi-track timeline displays colored blocks for segments like speech, tool calls, state transitions, silence, and barge-in events, with block colors communicating meaning: caller tone, agent greeting versus filler versus interrupted speech, tool success or failure, and system events. When a recording is available, a playhead tracks the current position across all lanes and supports seeking to any point in the call.
The voice playground provides a turn-oriented inspection view from the observer evidence it receives. Depending on the turn, details can include the selected action, state transitions, tool input and output, latency, and caller emotion. Missing observer events produce correspondingly partial detail.
Smoke Tests
Agent Forge includes commands for verifying the public text-conversation path. Use forge platform conversation create to create a durable conversation, forge platform conversation send-message to send a REST turn, and forge platform conversation poll when background work remains pending. The Go build's text-ws-smoke command is deferred and does not run the Sessions WebSocket test; the legacy Python build retains that smoke command. See Agent Forge CLI for usage.
The text Playground exercises the public conversation-create, turn, history, and close operations through one interface. For an executable client with independent history and closure checks, use First Verified Conversation.
Test Traffic and Billing
Supported test paths attach non-production source or traffic-class markers so downstream pipelines can exclude them from production reporting.
Test calls in Runs - Simulation-originated calls appear in the Developer Console's unified Runs view as "Test Call" entries, distinguished from inbound and outbound production calls.
Test caller numbers (voice) - Workspaces can designate specific phone numbers as test caller numbers. Inbound calls from these numbers are tagged as test traffic and excluded from billing, metric scores, analytics, and entity views. The call follows the normal inbound path for credentials, greeting, and audio, but its tools run in simulation mode and return a
dry_runresult instead of executing.Test credentials (text) - The same concept extends to text channels through a test credential allowlist. Text turns initiated by a designated test credential are tagged as test traffic, excluded identically to voice test caller numbers, and run tools in simulation mode. The allowlist applies only to workspace-authenticated credentials, not external user credentials. Text Playground sessions and browser test calls run tools live.
Playground exclusion - Playground-originated voice calls are excluded from metric projection. Text Playground sessions use the ordinary conversation API; the Console view alone does not establish a non-production traffic classification. Confirm the test configuration before relying on reporting exclusions.
Managing test caller numbers and test credentials requires workspace admin or owner permissions.
Simulation usage is metered and priced separately from production usage: every billing meter carries a traffic class, so testing activity does not inflate production cost reporting and simulation traffic can carry different rates. Simulation metering covers run completions, wall-clock simulation time, evaluation results, and LLM token consumption for scenario generation, evaluation judging, and simulated caller turns.
Last updated
Was this helpful?