> ## Documentation Index > Fetch the complete documentation index at: https://docs.bland.ai/llms.txt > Use this file to discover all available pages before exploring further. # Environments > Ship an agent safely: what development, staging and production hold, how to publish and promote, and why a call needs a production version Every agent has three environments: development, staging and production. Development is the agent you are working on, saved work and unsaved alike. It is the only one you edit. Staging and production are snapshots. Each holds one version of the agent and keeps serving it until you point it at another. A new agent has nothing in either. ## Prerequisites * An agent you have built, from [Agent builder](https://docs.bland.ai/agents/agent-builder.md) * An owner, admin, operator or prompter role. A viewer can see the Environments tab but cannot publish, promote, roll back or save a variable * Optional: evaluations configured on staging, if you want them to gate the publish into staging and the promotion out of it. See [Evaluations](https://docs.bland.ai/agents/evaluations.md) ## Where environments live Inside an agent, Environments is under Configure. It has two tabs, Environments and Variables. There is no organization-wide view. Environments belong to one agent, and you reach them from that agent. The Environments tab lists the release as rows that read from the bottom up: Development, Staging, Evaluations, Experiment and Production. Production sits at the top because it is where the other rows lead. Expand a row to see its details. Staging and production each show the **Version** they are pinned to, and usually when it arrived, **Deployed** on production and **Created** on staging. Development shows neither, because it is the live head rather than a pin. Production holding nothing shows no version. The controls that act on what is live, **Rollback**, **Staged rollout** and **Promote**, sit in the page header above the rows. [Staged releases walkthrough](https://www.loom.com/embed/7e7c48f0d9484c3e9348de72db5d61ce) > [!WARNING] > > A call runs the **production** version by default. An agent with nothing pinned to production has nothing to serve, and an API call is refused with a 400 and the code `AGENT_ENV_UNPINNED`. > > Building and saving is not shipping. ## Publish **Publish** sits in two places and does the same thing in both: the button at the top right of the builder, and the Development row on the Environments tab. It saves your current work as a new version, then ships that exact version somewhere. Where it ships depends on one thing: whether this agent has ever been in production. ### The first publish goes straight to production An agent that has never been live skips staging. There is no menu, just one button. The confirmation asks for a phone number, and tells you that publishing changes what the agent answers but not which numbers or pathways reach it. You can publish without attaching one. Staging gets the same version on the way through, so it does not start out behind. > [!NOTE] > > Configuring a required evaluation puts the agent back on the normal staging path, since a one-press release would have nothing to evaluate against. ### After that, Publish offers a choice Once production holds a version, Publish opens a menu of destinations: * **Publish to staging** saves a new version and pins it to staging. Production does not move, so callers keep the version it already holds. * **Force promote** sends development straight to production in one step, skipping staging. Staging is repointed to that version on the way, which the confirmation says outright. * **Staged release to Production** releases the new version to production gradually. See [Staged release](#staged-release). Picking from the menu is not agreeing to ship. Each destination opens its own confirmation. > [!WARNING] > > What **Force promote** skips is the evaluation gate. That is its purpose, and the bypass is recorded in the audit log rather than on the deployment, so deployment history will not show you which releases were forced. > > It is the control that puts unevaluated work in front of live callers. ## Promote to production **Promote** in the Environments page header points production at the version staging is holding. Nothing is copied and nothing is rebuilt. Its confirmation carries the same phone number section and the same reassurance as the first publish: promoting does not change which numbers or pathways reach the agent. ## Staged release A staged release is the middle path between publishing to staging and promoting everything at once. It splits production traffic between the new version and the version live now. You choose how much traffic goes to the new version and raise its share step by step. Staged release is available when all of these are true: * Your organization is on an enterprise plan. * Production already holds a version to split traffic away from. * No rollout is live for this agent. You can start a staged release from three places: * **Publish menu**: select **Staged release to Production**, then **Set up staged release**. Bland saves your work, runs your evaluations, and publishes the version to staging. It then opens Experiment settings on a new draft. * **Promote confirmation**: select **Staged release** beside **Promote to Production**. The version is already on staging, so the draft opens without publishing anything. * **Staged rollout** in the Environments page header. The draft splits traffic between the version in production and the new version. Review the plan, then select **Start experiment**. No production traffic moves until you start it. ### Plan the steps The plan is a list of steps. Each step sends a share of production traffic to the new version and holds it there until a date. Select a step's **Hold until** date to pick a new one from the calendar. A step can hold for up to 14 days. The **Standard** plan starts with these steps: | Traffic | Hold until | | - | - | | 5% | 4 days after the start | | 25% | 4 days after the previous step | | 50% | 7 days after the previous step | | 100% | 7 days after the previous step | Dates count from **Start on** when you set it, otherwise from when you opened the plan. Changing **Start on** moves the dates of a preset plan to match. Dates the plan fills in for you never land on a weekend. A Saturday or Sunday moves to the following Monday. This applies to preset steps, steps added with **Add step**, and later steps pushed out by an earlier edit. A date you pick yourself stays as you picked it, weekends included. When you move a step's date, later steps keep their dates. A later step that would no longer end after the step before it moves out by its own hold length. > [!NOTE] > > The dates are a plan. A step that needs approval waits for it, and every step after it slides by that wait. > [!NOTE] > > A staged release never skips the evaluation gate. Starting the experiment checks the same required evaluations as a promotion, so a version that can't be promoted can't be released in stages either. ## Attach a number to staging On enterprise plans, you can point a phone number at staging instead of production. Calls to that number run the version pinned to staging, so you can dial the staging version before you promote it. 1. Publish to staging first. With nothing on staging, the Staging option is disabled and reads **Not deployed**. 2. Inside the agent, open Channels, then the Calls tab, and select **Add a number**. 3. In Attach a number, pick the number, then set **Environment** to **Staging**. Each option shows the version deployed to that environment. Every number on the Channels page shows which environment it answers on, **Production** or **Staging**. > [!WARNING] > > Only calls follow staging. Texts to a staging number still run the production version. A staging number runs staging's variable values, so every variable the agent references needs a staging value before you can attach. Numbers can't be attached to staging on dedicated infrastructure. To move a number back to production, detach it and attach it again with **Production** selected. ## Roll back To go back, **Rollback** in the Environments page header lists the versions production held before and repins to one you choose. It is a repoint, not a rebuild. ## Activity and version compare The **Activity** section below the rows is a change log for the agent. Each row records one event, such as **Version saved**, **Published to staging**, **Promoted to production** or **Rolled back production**. Each row shows: * **Prior version**: what that environment was pinned to before the event. For **Version saved**, it is the previous save. A first publish shows a dash. * **New version**: the version the event put in place. * **By** and **When**: who made the change and when it happened. * **Compare**: opens the two versions side by side. To see what changed between two versions, select **Compare** or either version on a row. The compare window opens on that row's pair. Use the **Before** and **After** pickers to compare any two published versions instead. Switch between two views: * **Simple** steps through each field that changed. * **JSON** shows the whole configuration of both versions side by side, with changed words highlighted. Unchanged lines fold away behind **Show N unchanged lines**. When two versions differ too much to line up in the JSON view, the window points you to **Simple** instead. Rows have no **Compare** when both sides are the same version, or when either side has no published version number. ## The evaluation gate Evaluations on staging can gate both moves, and the two directions fail differently. You attach them from the Evaluations row above Staging, covered in [Evaluations](https://docs.bland.ai/agents/evaluations.md#make-it-a-required-check). With no evaluations configured at all, neither move is gated and both happen immediately. Configuring any evaluation changes that, even one you have not marked **Req'd**. The run still executes and the publish waits for it, which takes as long as the conversations take. What the required flag decides is whether a verdict can stop you: a judge, the evaluation that scores a run, reports its result and blocks nothing when it is not required. > [!NOTE] > > One evaluation configuration does both jobs. The one saved on **staging** gates the publish into staging and the promotion out of it. There is no separate production gate to configure. Publishing to staging saves your changes as a new version, runs the evaluations against that exact version, and only assigns it a version number and pins it to staging once every required evaluation passes. When a required evaluation fails, a toast reads **Publish blocked** with the number that failed. A run that times out or errors stops the publish too, with its own message. > [!WARNING] > > A blocked publish is not a rollback. The version is already saved on development, without a number and without a pin, and it stays there. > > Nothing is undone and nothing is lost. Fix what failed and publish again. A blocked promotion is stopped twice. The dashboard dims **Promote**, explains why on hover, and does nothing if you press it. The server enforces the same rule again on the wire, which is what catches an API caller. Either way production keeps serving the version it already had. A judge scores a rate, not a verdict per conversation. It passes when half or more of the scored conversations match the target, so a single bad conversation does not necessarily fail the run. Test cases default to an odd number of conversations, which keeps ties rare. ## Variables The Variables tab holds keys and values that belong to an environment rather than to the agent. Pick Development, Staging or Production to choose which set you are editing. The same key can carry a different value in development, staging and production. Reference one anywhere in the agent's configuration as `{"{{env.KEY}}"}`, and it resolves to the running environment's value when a call starts, which is how an agent points at a test system while it is on staging and a real one once it is promoted. A variable nothing references does nothing. Marking a value **Secret** stores it in your secret vault and keeps only a reference here. It cannot be read back afterwards. > [!WARNING] > > A key with no value in the environment the call is running in does not fall back to another environment. It fails the call before it starts, with `AGENT_VARIABLE_UNRESOLVED`. > > So a variable added on development and never set on production breaks production the moment something references it. ## Common failures > [accordion] The agent answers with old behavior > > Production is pinned to an older version. Publishing to staging does not move production; check what production says it is pinned to, then **Promote**. > [accordion] Calls fail and the agent looks fine in the builder > > The agent has never reached production. The builder shows development, which is not what a call runs by default. On an API call the error is a 400 with `AGENT_ENV_UNPINNED`, which also names the alternative: pass `agent_version` to run a specific version deliberately. > [accordion] Publish finished but staging did not move > > A required evaluation failed, and the toast said so. The version is saved on development with no number and no pin, which is why nothing appears to have happened on staging. > [accordion] Promotion is blocked although the evaluations passed > > The configuration changed after that run. Promotion compares the run against the whole configuration saved now, which covers the required evaluations and the shared test inputs, so changing the test cases or the conversation count invalidates a pass just as editing an evaluation does. Publish to staging again to run them against the current configuration. > [accordion] A button does nothing and the error says nothing > > Publishing, promoting, rolling back and saving a variable all need an owner, admin, operator or prompter role. The buttons are not disabled for a viewer, so the press fails with a generic message rather than telling you the cause. > [accordion] A variable is right in one place and wrong in another > > Variables are per environment. Setting one on development leaves staging and production untouched, and promoting an agent does not carry values across. ## Next steps > [card] [Agent builder](https://docs.bland.ai/agents/agent-builder.md) > > Build the version you are going to publish. > [card] [Dispatch](https://docs.bland.ai/agents/dispatch.md) > > Give the promoted agent a number to answer on. > [card] [Conversations](https://docs.bland.ai/agents/conversations.md) > > Read what the production version actually did. > [card] [Tools](https://docs.bland.ai/agents/tools.md) > > The tools a version carries with it. Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.