Playground

The Playground is the test chat for agents. It lives at /organizations/{org}/workspaces/{ws}/playground, in the sidebar under the Workspace heading.

What it does

A simple chat UI:

• Pick an agent from the selector at the top.
• Type a message, send. Stop interrupts a reply that is still streaming.
• The reply streams in as it is produced, with each step’s tool calls and reasoning shown as they happen.

The Playground reuses the production pipeline. The same prompts, the same tools, the same memory. Its conversations are web conversations like any other API caller’s, and they appear on the Conversations screen.

Under the hood the Playground calls its own route, POST /api/instances/{slug}/playground/stream, with a chat_id that keeps the conversation together. It accepts the same body as the OpenAI-compatible endpoint and answers with the same typed event stream as the native streaming endpoint (steps, tool calls and results, reasoning, hook executions). It carries no call context.

The same chat also opens as a drawer on an agent’s own page, pinned to that agent. Closing the drawer keeps the conversation, so you can change a prompt and try again without starting over.

Access

The Playground signs in with your panel session, never with the agent’s API key, and it does not go through the agent’s Web/API channel. You can test an agent whose Web channel is off, or that has no key yet, which is how a new agent starts.

What decides access is the permission agent.playground:use on the agent’s workspace. Every built-in role holds it, Viewer included. With managed services, an upgrade to 1.2.0 granted it to every custom role that holds agent:write; a custom role without agent:write that should test agents needs it granted in the role editor. Without it, sending a message is refused with 403.

Show activity

The Show activity switch adds the agent’s work to the transcript: tool calls with their arguments and results, reasoning, hook executions and per-message details. It is one preference shared with the Conversations detail page, so turning it on in one place turns it on in the other.

A turn the agent buffers (an output governance gate, or a hook that can replace the response) arrives in one piece at the end rather than streaming; see Hooks → Streaming caveat.

Multi-turn conversations

A chat stays one conversation until you press New Chat. History lists the selected agent’s recent conversations and opens one in the chat, and the Conversation state button shows the state the conversation’s tools and hooks have written.

Use cases

• Iterating on prompts. Edit the Identity section, save, swing back to the Playground, ask the same test question, evaluate.
• Debugging tools. Turn on Show activity to see each tool call, its arguments and its result as the turn runs; the Conversations page shows the same calls once the turn is stored.
• Smoke-testing channels. When a Telegram or Slack channel misbehaves, reproducing the issue in the Playground confirms whether the bug is in the channel adapter or in the underlying pipeline.