Environments

Publishing an agent mints a version. An environment is a name that points at one of them — production, staging, dev — so you can try a new version somewhere before everybody meets it.

Without environments, publish and release are the same act. With them, they are two decisions: minting the version, and putting it somewhere.

What an environment is

A name, a version it is pinned to, and optionally its own tracing destination. Every agent has a default environment, and that is what a plain surface gets when nobody said otherwise.

Name	Lower-case, hyphenated, up to 64 characters — it appears in URLs and becomes the tracing tag, so Production (EU) and production-eu must not be two things
Version	Which published version answers here. There is no unpinned state
Tracks latest	Whether publishing repoints this environment on its own. Off by default
Tracing	A Logfire write token from the vault, so this environment's runs land in their own project

There is no environment without a version

An unpinned environment would be a name that answers with nothing, and the first message routed to it would fail a long way from the form that created it. Create one without naming a version and it starts at whatever the default serves.

The workflow it is for

flowchart LR
    D[Draft in the Builder] -->|publish| V[Version 7]
    V -->|pin| S[staging]
    S -->|somebody tries it| OK{Good?}
    OK -->|yes| P[promote to production]
    OK -->|no| D

1. Edit the draft, publish. That mints a version and changes nothing anybody is using.
2. Point staging at it, and bind your test Slack bot or a private link to staging.
3. Try it against real questions.
4. Promote production onto the same version — one edit, no republishing.

Rolling back is the same move backwards: repoint production at the version that worked. The old version is still there, still readable, still runnable.

tracks_latest, and why it is off

An environment with tracks latest on is repointed by every publish. That is the right setting for dev and almost never right for production.

Off is the default deliberately: publishing mints a version, and deciding where that version runs is a separate act. Coupling them means an unfinished edit reaches a customer because somebody clicked Publish to save their work.

The one exception is the production a first publish creates. While it is the agent's only environment there is nothing to promote from, so it follows publishes; pin it once a dev or a staging sits beside it.

Binding a surface to one

An exposure — a Slack bot, a widget, a hosted page, an API audience — can name the environment it serves. Omitted, it gets the default.

That is what makes the split useful: a dev bot bound to dev serves whatever dev pins, while the widget on your website stays on production until you move it. One agent, two audiences, two versions, one set of books.

A page the agent publishes follows the same split. A run in a named environment publishes an app of its own, so trying dev on the weekly report never republishes the page production readers open. An environment with a run still working, or waiting for an approval, cannot be removed until the run ends: deleting it would hand that run to the default, and its pages to production's.

Trying it from the Builder

Test, in the Builder's header, opens a chat beside the Builder rather than over it - the same chat as /chat, with streaming, tool steps, approval cards and questions. It answers as the draft, with your unpublished changes, or as any environment's version, and says which. Nothing is published to test the draft: it must pass the checks a publish makes, and only somebody who may edit the agent can run it. A run parked on an approval continues on the draft as it was when the run started.

Every turn there is a test run: budgeted and recorded like any other, marked test in Activity, and filterable there (With test runs, Without test runs, Only test runs; ?test=true or false on GET /api/v1/runs). The panel starts a new conversation, sends the last message again after an edit, and keeps a few pinned prompts to rerun in one click. Its width, what answers and the pins are remembered per agent in your browser. The chat frame sends draft: true, or test: true with an environment_id, on each turn.

Compare puts two chats side by side - the draft and production, or two environments - and the box above them asks both the same thing at once, so the answers differ only by what answers. What the draft changes shows the draft against the published version, as the same diff the version history draws. Pressing T anywhere on the Builder, outside a text field, opens or closes the panel.

Tracing per environment

An environment can carry its own Logfire write token, sealed in the vault, plus a service name. Its runs trace into that project, tagged with the environment's name.

This is what keeps a staging experiment out of the dashboard somebody watches for production incidents — and it is per environment rather than per deployment because the two are genuinely different projects.

Where the traces go is the environment's; how much they carry is the agent's. An agent's observability block has a content mode: full records the message, the model's output and every tool argument; none records timing, tokens, cost and tool names only. For a project over health, legal or HR data, none is what keeps a copy of the protected content from leaving the machine. The environment's token redirects the run but does not override that choice.

What the default environment is not

The default is managed by publishing, not by this API. You cannot delete it, rename another environment onto it, or hand-toggle which one is default.

Putting "what does a plain surface get" into two hands means they eventually disagree, and the disagreement surfaces as a customer meeting a version nobody released.

Recap

• An environment is a name pinned to a version; every agent has a default.
• Publishing mints a version. Putting it somewhere is a separate decision — that is why tracks_latest is off for an environment you add; the production a first publish creates follows until you pin it.
• A surface can name its environment, so a dev bot and a public widget can serve different versions of one agent.
• Rolling back is repointing, because old versions stay readable and runnable.
• The default environment is managed by publish, and deliberately not editable here.