> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/testing/testing/playground.md). # Playground and Interactive Testing This page covers interactive tools in the Developer Console and Agent Forge CLI: live playground conversations, standalone tool tests, call and turn timelines, endpoint smoke tests, and supported test-traffic classification. These tools provide fast development feedback; use [simulations](/testing/testing/simulations.md) for repeatable pre-deployment evidence. ## Playground Modes Open **Prove > 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. REST and SSE are implementation choices within text mode, not separate playground modes, and there is no realtime text-WebSocket mode. 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. 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](/channels/text-sessions.md) for the underlying REST/SSE contract. ### Live Inspection The playground streams user-visible response tokens and available observer events such as tool calls and state transitions. 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 observer connection. 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](https://docs.amigo.ai/developer-guide/platform-api/integrations/approval-gated-integration-writes) for the full contract. ### 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. 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](/reference/agent-forge.md#simulation-caller-and-entity-context) 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 Playground sessions start out lightweight - they are created without a [coverage](/testing/testing/simulations.md#simulation-coverage) run, so run-scoped operations like forking a session or scoring it are not available on a raw playground session. This keeps iteration fast: you can explore a conversation without paying for coverage bookkeeping you may not need. When a session turns out to be worth analyzing, you promote it. Promotion binds the run-less session to a newly created coverage run, which unblocks forking and scoring. It is idempotent - promoting a session that is already bound to a run returns the existing run unchanged - so you can iterate freely in the playground and then promote only the sessions you want to take further, without re-running the conversation. ### Branch Explorer The text playground includes a branch explorer for comparing how the agent responds to different caller phrasings from the same point in a conversation. You enter up to six alternative caller messages; the platform promotes the interactive session into a coverage run (if it is not already promoted), then forks the session into one branch per alternative. Each branch runs independently and its response is shown side by side, so you can see directly how a change in phrasing changes the agent's behavior. Each successful branch is stored as a child coverage session under the promoted run, so it can participate in coverage analysis. The branch explorer becomes available after the text session has a user 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=true` returns 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 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?** {% hint style="info" %} **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](https://docs.amigo.ai/developer-guide/platform-api/functions/tool-testing) in the developer guide. {% endhint %} ## 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](/reference/agent-forge.md#text-conversation-testing) for usage. The text playground exercises the same conversation-create and streaming-turn behavior through one text interface. ## 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, 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. {% hint style="info" %} **See also** * [Simulations](/testing/testing/simulations.md) for repeatable scenario-based verification and regression suites * [Voice Simulation](/testing/testing/voice-simulation.md) for choosing between text-tier coverage and real-audio validation * [Agent Forge CLI](/reference/agent-forge.md) for terminal-based testing commands {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/testing/testing/playground.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.