Agent SDK

Appearance

Playground ​

Every served agent ships with a web playground at http://127.0.0.1:3000/<slug>/playground (or /playground in single mode): a static SPA over the same public HTTP API, made for manual testing, demos, and reading sessions. Every call it makes runs the normal route auth chain, so anything you can do in the playground you can also do with curl.

What it does ​

The playground covers the whole manual-testing loop.

  • Chat with the agent. Text and reasoning stream live, rendered as markdown with syntax highlighting, and tool calls appear inline with their arguments, output, and error state as the actions.requested / action.result events arrive.
  • Slash commands: custom channel routes become composer commands (a drive route becomes /drive <pr-url>), derived from the schemas on GET /v1/info, with /help and autocomplete.
  • Try any channel route from the Agent surface. The modal remembers your last body per endpoint and has Copy curl, and a successful Try opens the created session.
  • Sessions: browse every session (chat, custom-channel, schedule tasks) and replay their durable event streams. Search by session ID to filter the list, or press Enter to open an ID directly. "Open trace" renders any events.ndjson file.
  • Approvals: parked needsApproval tool calls render Approve / Deny buttons.
  • Evals: list and run filesystem evals from the browser (backed by /v1/dev/evals). Schedule hand-dispatch still requires --dev.
  • The surface: inspect the discovered tools, skills, subagents, MCP connections, channels, and hooks.
  • Raw NDJSON pane: flip it on to see the exact wire events.
  • Logs tab: recent server log lines, polled from GET /v1/logs.
  • A/Bs tab: per-session and aggregate live A/B metrics from GET /v1/abs (folds durable ab.assigned plus turn and tool events; no separate store).

In multi-agent mode each agent has its own playground at /<slug>/playground, and / is an index of them all.

Share it beyond localhost ​

The default localDevStrict() auth admits direct loopback calls only and rejects proxy-forwarding headers, so a tunnel or LAN address won't work until you pass --bearer-token <secret> (or serve(dir, { authToken })). Open the playground on the remote device and paste the token into the token field in the navbar. --allow-anonymous is the demo-only alternative for trusted networks.

What's next ​

Continue with these pages: