Playground and Interactive Testing

Test agents interactively in the Developer Console playground - voice, text, and streaming modes, isolated tool testing, call timelines, and test traffic rules.

This page covers the interactive testing tools built into the Developer Console and the Agent Forge CLI: the playground for live conversations with your agent, isolated tool testing, call and turn timelines for inspecting what happened, smoke tests for conversation endpoints, and the test traffic controls that keep testing activity out of production billing and analytics. These tools give immediate feedback during development; for repeatable pre-deployment verification, use simulations.

Playground Modes

The Developer Console playground lets you test any active service through three modes from a single interface:

• Voice - a browser-based voice call with live audio
• Text - a turn-by-turn text conversation
• Realtime - a streaming text conversation over WebSocket, showing messages in real time with automatic reconnection

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.

The playground layout supports toggling side panels (context graph, event log) through keyboard shortcuts or toolbar buttons. See Text Sessions for details on the underlying channels.

Live Inspection

The playground shows what is happening as it happens. Playground and simulation sessions stream LLM tokens, tool calls, and state transitions to the Developer Console in real time - the same view available for live voice sessions. The inline agent trace shows each tool call with its execution duration, and the interface indicates while an agent response is in flight so you always see current state.

When a background skill or deferred tool completes during an active session, its result - and any follow-up message the agent produces outside the normal turn cycle - appears live in the conversation timeline without waiting for the next turn. Completions belonging to a different conversation or arriving after the session ends are ignored, and deduplication ensures nothing is shown twice. If a turn fails mid-session, the playground surfaces the error in a banner rather than silently showing no response.

Approval Gates in the Playground

When an integration with an approval gate parks a write during a text playground conversation, an inline approval card appears above the chat input showing the tool name with Approve and Reject controls. Approving lets the agent proceed with the call; rejecting declines it with an optional reason the agent sees and narrates on that same turn. The decision is durably recorded and consumed on the conversation's next turn in any mode - REST, streaming, or SMS - so approval does not depend on an active streaming connection. Approved writes appear as first-class tool calls in the turn's tool-call logs, with input parameters, result, success status, and execution duration, and the agent explicitly narrates whether the action was approved and completed. See Approval-Gated Integration Writes in the developer guide for the full approval model.

Caller Identity

Both voice and text playgrounds support setting a simulated caller phone number before starting a session. The caller identity is forwarded to the engine so it can run patient resolution, letting you test caller-specific behavior - greeting a known patient by name or loading their clinical context - without making a real phone call or connecting to a live telephony provider. The caller number is remembered per playground mode between visits. Leaving the field blank omits the caller identity, so the engine uses its default caller with no patient match.

The Agent Forge CLI simulation commands (session-create, smoke-test, and bridge) accept a --caller-id flag that does the same thing from the terminal: set a simulated caller phone number in E.164 format so the session starts with full patient context. Omit the flag 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.

Tool Testing

The tool testing playground lets you execute individual context graph tools - world tools, skills, and integrations - in isolation without making a phone call or starting a text session. This is useful during development when you need to verify that a tool behaves correctly before wiring it into a full conversation flow.

Tool testing runs against the live world model but with safety guardrails:

• Source isolation - All writes from tool tests are tagged with a dedicated test source, which is excluded from outbound sync. No real EHR writes, SMS deliveries, or external side effects happen.
• Surface delivery blocking - Surfaces created during tool tests are blocked from delivery to patients.
• Dry run mode - Write tools can be executed in dry run mode, which simulates the operation and reports what would have happened without persisting anything.

For each tool, the playground resolves the full tool definition (input schema, description, tier, write/read classification) and lets you provide custom input parameters and an optional entity context. After execution, you see the result, execution duration, any sub-tool calls that were made, and a list of blocked side effects.

Simulation and playground sessions also produce visible entity state in the world model. Events from these sessions are included in entity state projections so that testing workflows reflect the same data the agent would see in production. Other analytical pipelines (metrics, encounter detection, gap detection) continue to filter these events out, keeping production analytics clean.

Tool testing answers the question: does this tool do what I expect with this input?

Permissions: Tool testing requires admin or owner access to the workspace. This is a developer workflow, not a production testing mechanism - use simulations for pre-deployment validation. For the API surface, see Tool Testing in the developer guide.

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

Every call has a structured timeline representation of its conversation flow: who spoke, when, and what occurred, broken into segments with actor semantics. Segments are organized into tracks corresponding to the participants - Caller, Agent, Operator, Tools, and System - so call activity can be filtered, grouped, and visualized by participant rather than just by time. The timeline is available in the Developer Console's call detail view and through the API for embedded playback and timeline-only consumers, and it is consistent across calls regardless of when they were made.

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 adds a turn-by-turn timeline for structured inspection of every conversation turn during a live or completed session: a compact turn list with color-coded event summaries alongside a detail panel showing the selected action, state transitions, tool calls with expandable input and output, latency breakdown, and caller emotion data. The timeline links bidirectionally with the transcript - clicking a message selects the corresponding turn and vice versa - and clicking a state in the context graph panel shows the actions available in that state.

Smoke Tests

Agent Forge includes smoke test commands for verifying text conversation endpoints. Use forge platform conversation create to create a conversation, then forge platform conversation send-message to send turns through the REST API and display the agent's response. The WebSocket smoke-test command, forge platform conversation text-ws-smoke, opens the session WebSocket, sends one message, and requires an agent response. See Agent Forge CLI for usage.

The playground provides interactive equivalents of these smoke tests through its text and realtime modes.

Test Traffic and Billing

Testing activity is classified separately from production traffic so it never distorts production reporting.

• Test calls in the call log - Simulation-originated calls appear in the Developer Console call log 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, EHR outbound, and entity views. The call itself follows the normal inbound path - credentials, greeting, and audio pipeline are unchanged - only the classification is affected.
• 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 and excluded identically to voice test caller numbers. The allowlist applies only to workspace-authenticated credentials, not external user credentials.
• Playground exclusion - Playground-originated calls are excluded from metric projection, so interactive testing does not affect production or simulation metrics.

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.

See also

• Simulations for repeatable scenario-based verification and regression suites
• Voice Simulation for voice configuration exploration
• Agent Forge CLI for terminal-based testing commands