Environments and releases
How environments and releases work
The path Development → Staging → Production, the draft, what a release holds and what every environment shares, which channel uses which environment, and what changed for new and existing agents.
Concept4 min readUpdated 1 November 2026
Every workspace has a promotion path: Development → Staging → Production, plus any environment you add, such as QA. Development is where you change and test an agent: it runs the agent as you last saved it, the draft. Staging and Production never run a draft, only releases: numbered snapshots you make by promoting, which can't be edited, only promoted again or rolled back. The widget, chat links and the API use Production unless they name another environment; the Playground and the Build tab's test chat use Development.
The path
| Environment | Slug | What it is |
|---|---|---|
| Development | development | Each agent's draft, the only editable one. Saving a change updates it; the Playground, the Build tab's test chat, Compare and experiments use it |
| Staging | staging | "Try a release before it goes live." Takes a release promoted from Development |
| Production | production | "What your customers use." The default environment: the widget, chat links and the API use it unless they name another. Protected (only workspace admins promote into it or roll it back), and it requires Staging first: it only takes a release that Staging runs |
Rename, recolour, reorder, add and remove environments under Settings → Workspace → Environments; the slugs never change. See Add, rename, reorder and remove environments.
What a release is
Promoting from Development makes a release: v1, v2 and so on, a snapshot of everything that decides how the agent behaves. It never changes. Promoting it again moves the same release to the next environment, so what you tested in Staging is exactly what Production runs. Each release has optional notes, who made it, when, and a digest (the first 12 characters of a SHA-256 of its contents), which is the same for two releases with the same configuration.
| In a release (per environment) | Shared by every environment |
|---|---|
| Instructions (the system prompt) | Name, description and icon |
| Provider and model | The provider API key |
| Temperature, max tokens, top P, frequency and presence penalties | Knowledge: documents, websites, snippets and Q&A |
| Output format | MCP servers |
| Tools: the built-in tools and app actions switched on in the Toolbox | App connections |
| Guardrails attached to the agent | Token prices for cost reports |
| Knowledge on or off | Active or Paused |
| The workflow it answers with | |
| Its rate limit (requests a minute) |
So adding a document or a new MCP server changes answers in every environment at once, while a new instruction or model only changes Development until you promote. The agent's Settings tab tells you which kind you saved: Saved to Development. Promote to release it. or Saved. This applies to every environment.
Who uses which environment
| Traffic | Environment |
|---|---|
| Website widget | The default (Production), unless you pick another for it on the agent's Deploy tab |
| Chat link | The default, unless you pick another in the link's settings on the Deploy tab |
API: /v1/chat and /v1/chat/stream | The default, unless the request sends X-Environment or environment |
| Playground | Development, unless you pick another in its environment picker |
| The Build tab's test chat, and Compare | Development, always |
| Experiments | Development: they test the draft, and your variants of it |
| Workflow test runs in the designer | Development, for each agent step |
| Live workflow runs: webhook, API, schedule, chats | The default, unless the API call sends environment |
| An agent that answers with a workflow | The workflow runs in the chat's environment, so its agent steps use their agents' releases there |
Every conversation records the environment that answered: Conversations shows it in its own column and filter, and the API's meta event carries it. Details and examples: Choose which environment answers.
New agents, and agents from before environments
- A new agent is in Development only: its Staging and Production pills read Not released, the agents list shows Not released, and the widget, chat link and API answer
409 AGENT_NOT_DEPLOYEDuntil you promote it. The Build tab's test chat and the Playground work from the start. - Every agent that existed when environments arrived (in production on 2026-11-01) got v1, "what the agent ran when environments were turned on", in Staging and Production. Nothing changed for its widget, chat link or API.
- From then on, saving a change marks Development with the number of unreleased changes, and the agents list shows an amber dot: Unreleased changes in Development.
Where you see it
- Agents: an Environments column with a chip per environment running a release, such as Staging v4 and Production v3.
- The agent's page: the environment bar under its name, one pill per environment with what it runs. Click a pill to see that environment, and Promote to Staging (or the next environment) to make a release. See Promote a release.
- The agent's Overview: the Channels table says which environment each channel uses.
- The agent's Releases tab: every release, where it runs, compare and download. See The Releases tab, release views and the artifact.
- Settings → Workspace → Environments: the path, with how many agents run a release in each.
Who can promote
Editors promote into environments that aren't protected, and viewers only read; workspace admins also promote into protected environments, roll them back and change the path. Organization owners and admins are admins of every workspace. Every promotion, rollback and environment change is in the organization's audit log. See Roles and permissions.
Is a release the same as an edit in Edit history?
No. Edit history records every saved change to the draft (Development) and lets you restore one. A release is a snapshot made when you promote, and is what Staging and Production run.
Do I have to use Staging?
By default Production only takes a release that Staging runs. A workspace admin can switch that rule off on Production, or remove Staging, under Settings → Workspace → Environments.
Does a release include the knowledge?
Only whether knowledge is on. The documents themselves are shared, so a document added today is used by every environment.
Related
Still stuck?
Email us with what you tried and any request id. A person replies.