> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepatchwork.co/llms.txt
> Use this file to discover all available pages before exploring further.

# The Playground

> Talk to your agent from the dashboard with no client code to write, and check your backend is wired correctly before you build against it.

The Playground runs your published agent from inside the dashboard. No API key, no thread management, no client code. You pick an agent, pick who to run as, and start talking.

It replaces the *client* half of an integration, not the server half. Tool calls egress for real, so an agent whose patches reach your endpoints needs its [connection](/guides/connections) already working — `mint_url` included — before the Playground can tell you anything. What it saves you is writing a client to find that out.

Use it for two different jobs: iterating on the agent itself, and proving your backend works before you build a client against it.

## Running as someone

An agent run needs a [subject](/guides/subjects), so the Playground gives you **personas** — a named subject bound to a connection.

| Field | Meaning |
| - | - |
| **Label** | What you call it — "New customer", "Returning user with an order". |
| **Subject** | The actual `subject_ref` string the run uses. |
| **Connection** | Which of your hosts this persona's tool calls go to. |

Personas are unique per connection and subject, so the same string is one persona per host. Switching personas switches thread history and memory with it, because both partition on the subject — which makes personas the fastest way to see what a returning user experiences versus a first-time one.

### Use a subject your backend knows

A persona's subject is not a placeholder. It becomes the run's `subject_ref` and travels the egress chain unchanged — Patchwork posts it to your `mint_url` as `{ "subject": "…" }`, you mint a token whose `sub` is that string, and your endpoint reads it.

So if your tools resolve a subject, the persona has to name one your system can actually find. A persona of `test-persona-1` arrives at your backend as a user id that does not exist, and your endpoint rejects it — or resolves it to nothing and appears to succeed.

The **Label** field exists so personas can have friendly names. Put "New customer" there, and a real identifier — ideally a seeded test account, in the exact shape production will use — in the subject.

If your tools do not care who is asking, none of this applies and any string will do.

## What you get on every run

Everything the API gives you, in the panel beside the conversation:

* **The trace** — every model call, every tool call, arguments, results, timings, cost. Same [trace](/guides/traces) the API returns.
* **Memory** — facts and episodes the agent has accumulated for that persona, with the ability to delete one or forget the subject entirely.
* **Threads** — saved conversations per persona, so you can return to one.

The memory panel is the useful one while iterating. If an agent keeps volunteering something stale, you can see the fact it learned and remove it, rather than guessing.

## Playground memory is separate

Playground threads are recorded with a sandbox origin, and subject memory keeps live and sandbox partitions apart. Experimenting will not teach your production agent anything, and production conversations will not leak into your testing.

That isolation covers the Playground only. Traffic you send through the API is `live` even when you think of it as a test — prefix those subjects if you want them separately erasable. See [Memory](/guides/memory).

## Testing your backend before you integrate

This is the part worth planning around. The Playground exercises the same egress path as production: if your agent wires a patch that calls your host, the Playground really calls it, signed, with a real subject.

So you can have your connection, your patches, and your tool endpoints working — verified end to end — before writing a single line of integration code.

<Warning>
  **A `minted` connection is only testable here if your mint endpoint handles the relay branch.**

  Playground runs are trusted-internal: there is no browser and no session token on the request, so Patchwork can only mint server-to-server against your `mint_url`. If you built only the browser-session half of [the mint endpoint](/guides/mint-endpoint), the run fails partway through with:

  ```
  minted egress needs a session token or a connection mint_url
  ```

  Build the relay branch first. Your product needs it eventually and the Playground needs it immediately.
</Warning>

## A sensible order

<Steps>
  <Step title="Publish an agent with no patches">
    Every agent can already ask questions and hand off. Get the system prompt right against a persona before anything touches your backend. See [Your first agent](/first-agent).
  </Step>

  <Step title="Create a connection and press Test">
    You want `verified`, not merely `reachable` — see [Connections](/guides/connections#testing-one). This proves your request secret matches before any agent depends on it.
  </Step>

  <Step title="Wire one read-only patch">
    Run it in the Playground and read the trace. The `request` on the tool call shows exactly what reached your host.
  </Step>

  <Step title="Wire a write, set to Always ask">
    Approve and reject it in the Playground and watch both paths in the trace. See [Confirmations](/guides/confirmations).
  </Step>

  <Step title="Only then integrate">
    By this point the agent, connection, patches, signing, and minting are all proven. What is left is client code.
  </Step>
</Steps>

## What the Playground cannot show you

It is relay-shaped by construction, so a few things only appear once you integrate:

| Not exercised here | Where it first runs |
| - | - |
| Direct ingress — signed session tokens, JWKS, allowed origins | Your browser integration |
| The direct branch of your mint endpoint | Your frontend calling it |
| Realtime streaming to a client | Your app's subscription |
| Your own thread and subject management | Your backend |

A connection whose egress only works by reusing a browser JWT cannot be driven here at all — there is no browser and no JWT. That is not a Playground limitation to route around; it is the same reason relay exists.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.