> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/testing/testing/playground.md).

# Playground and Interactive Testing

Test agents interactively in the Developer Console playground through voice or text, with an execution stream, an inspector, 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](https://docs.concurrence.com/developer-guide/guides/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](/testing/testing/simulations.md). Use simulations for repeatable pre-deployment evidence.

## Playground Modes

Open **Evaluate > Playground** in the Developer Console. Each active service appears as a card with its description, its channel, and the agent and Context Graph it runs, each with the version the service's release pins, or **Latest** when no release is set. Search for a service or filter the cards by channel. Choose **Test** to open the service in its configured mode:

* **Voice** - a browser-based voice call with live audio, for a voice service
* **Text** - a turn-by-turn text conversation, for a text service

The Console runs text mode on the public conversation operations and background-delivery events; see [Text Sessions](/channels/text-sessions.md) for the underlying REST/SSE contract.

A **Start a session** dialog opens before each session. In text mode it sets who speaks first, **User first** or **Agent first**, an optional **Test identity**, and any declared conversation context. In voice mode it sets the microphone and an optional **Caller ID**. Both note that the session is a real conversation whose tools can read and change connected systems, and text mode lists the service's known tools that can make changes. Starting stays disabled until the service has published agent and Context Graph versions. In user-first mode, the session waits for your opening message. In agent-first mode, the agent opens with its greeting.

When the service declares `accepted_context`, the text start dialog includes 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](https://docs.concurrence.com/developer-guide/guides/conversation-context) for the service schema and binding setup.

### Live Inspection

A text or voice session shows an execution stream. Each turn shows the user's message, its state changes, every tool call, and the agent's response, with timing and, on voice, interruption evidence. On text, each state change names the exit condition it took. A tool call stays collapsed until you open it, then shows its inputs and result together. Messages have a copy action, and a long tool error is shortened, with options to expand and copy it. The session header shows its status and current state.

A resizable inspector beside the stream has four tabs:

* **Stream** - the session's turns and the operations each recorded, with search, a failed-only filter, and the prompt logs, which load when you open them.
* **Agent** and **Context graph** - the configuration the service's release pins, or the latest version when no release is set. The Console notes that this does not confirm which version the session ran.
* **Session** - totals, the current state, anything that needs attention, such as a pending approval or a failed tool, and the executed state path.

Text mode shows conversation responses and available persisted turn details, supplemented by live background-delivery events for the session's own conversation only. Voice mode uses its live observer connection. The stream 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 stream. The Console doesn't resend a turn that fails. After a send error it reloads the conversation, so a turn the server finished still appears.

A text session that fails to start shows the API's reason in the start dialog. If ending the session fails, the session stays live with the error, so you can end it again. Reloading the page reopens the same conversation.

### 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.concurrence.com/developer-guide/platform-api/integrations/approval-gated-integration-writes) for the full contract.

### Caller Identity

The start dialog sets the identity for the session. Voice mode exposes **Caller ID**, the phone number used to identify the caller; blank uses the default playground caller, which matches no patient. Text mode exposes **Test identity**, the UUID of the entity the conversation is about; a value that isn't a UUID is flagged before the session can start. 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](/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

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](/testing/testing/simulations.md).

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](https://docs.concurrence.com/developer-guide/platform-api/safety/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](https://docs.concurrence.com/developer-guide/platform-api/safety/simulation-coverage). 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=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-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](#test-traffic-and-billing).

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.concurrence.com/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 Python build's `text-ws-smoke` command tests the Sessions WebSocket. See [Agent Forge CLI](/reference/agent-forge.md#text-conversation-testing) 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](https://docs.concurrence.com/developer-guide/guides/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** - In the Developer Console's unified Runs view, a run's **Direction** detail distinguishes playground, simulated, and test calls 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_run` result 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.

{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/testing/testing/playground.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.