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

# Agent lifecycle phases

> Keep experimental agents in a sandbox and promote them to production when they are ready, with phase-specific credentials and a credit reserve

Lifecycle phases separate the agents you are still building and testing from the ones doing real work. Every agent is either a **sandbox** agent or a **production** agent: sandbox agents can be kept away from live credentials, real integrations, and the workspace's last credits, while production agents run with full access.

<Note>
  Lifecycle phases are enabled per workspace on request — contact [support@abundly.ai](mailto:support@abundly.ai). Once
  enabled, a workspace admin turns the phases on under **Workspace → Settings → Agent lifecycle phases**.
</Note>

<Frame>
  <img src="https://mintcdn.com/abundly/vyaau6-RKUVmQBYV/images/agent-lifecycle-settings.png?fit=max&auto=format&n=vyaau6-RKUVmQBYV&q=85&s=9864c0e3898e73749f9587e1511f863f" alt="Workspace settings card for agent lifecycle phases: the enable toggle, the Sandbox and Production phases side by side with what each means, and the settings for who can promote agents and how many credits are reserved for production" style={{ width: "700px", height: "auto" }} width="1400" height="681" data-path="images/agent-lifecycle-settings.png" />
</Frame>

## The two phases

|                               | **Sandbox**                                                                  | **Production**                                         |
| ----------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Which agents**              | Every agent starts here                                                      | Agents that have been promoted                         |
| **Production-only resources** | Cannot use capabilities, secrets, or API Capabilities marked production only | Full access to everything the agent is configured with |
| **Secret values**             | Uses a secret's sandbox value when one is set, for example a test API key    | Uses the main value of every secret                    |
| **Agent-to-agent**            | Talks to other sandbox agents only                                           | Talks to other production agents only                  |
| **Credits**                   | Pauses when the workspace balance falls to the production reserve            | Keeps running on the reserved credits                  |

Sandbox agents know which phase they are in. When a sandbox agent runs into a production-only resource or the credit reserve, it explains the restriction and who can promote it.

## How it works

1. **Turn phases on:** A workspace admin enables lifecycle phases in workspace settings. Every existing agent becomes a sandbox agent, and nothing changes for them yet — no resource is production only until you mark one.
2. **Mark resources:** Restrict the capabilities, secrets, and API Capabilities that sandbox agents must not touch to production, and give secrets a sandbox value where a test credential exists.
3. **Build and test in the sandbox:** New agents start in the sandbox, where they can be developed safely against test credentials and other sandbox agents.
4. **Promote:** When an agent has been tested, promote it under the agent's **Settings → Lifecycle phase**, or promote several at once with the **Change phase** bulk action on the [Agent management](/features/agent-management) page.
5. **Demote when needed:** An agent can be moved back to the sandbox at any time. Its configuration is kept — promote it again to restore access.

Every phase change is recorded in the workspace audit log.

## Marking resources for a phase

A resource that is not marked is available to agents in both phases.

* **Capabilities** — On the workspace **Capabilities** page, mark a capability as production only. Team admins can tighten this for their team but cannot make a production-only capability available to sandbox agents.
* **Secrets** — Each secret has a **Phase availability** setting (all phases, production only, or sandbox only) and an optional **Sandbox value**. With a sandbox value in place, sandbox agents use it instead of the main value, so a test key never has to be swapped in and out by hand.
* **API Capabilities** — Each API Capability has the same **Phase availability** setting, so a live integration can be restricted to production agents while a staging endpoint stays sandbox only.

<Tip>
  Sandbox-only markings are useful too: a secret or API Capability that points at a test system can be marked sandbox
  only, so it is never used by a production agent by mistake.
</Tip>

## Agent-to-agent communication

By default agents only contact agents in the same phase, so a sandbox agent cannot pull a production agent into an experiment. If a production agent should be reachable from the sandbox too — a shared lookup agent, for example — turn on **Reachable from all phases** in that agent's [Agent Communication](/features/multi-agent#agent-to-agent-communication) settings.

## Workspace settings

Under **Workspace → Settings → Agent lifecycle phases**, a workspace admin controls:

* **Enable lifecycle phases** — the master switch for the workspace.
* **Who can promote or demote agents** — workspace admins, team admins, or agent owners. Each option also includes the broader admins above it, so workspace admins can always change a phase.
* **Credits reserved for production agents** — when the workspace balance falls to this amount, sandbox agents pause and the remaining credits are kept for production agents. A paused sandbox agent tells the user that a workspace admin can promote it or lower the reserve.

## Where to find it

* **Workspace → Settings → Agent lifecycle phases** — enable the feature, choose who may change phases, set the credit reserve
* **Agent → Settings → Lifecycle phase** — promote or demote a single agent
* **Agent management** — filter agents by phase and change the phase of several agents at once
* **Shared Assets → Secrets / API Capabilities** and **Capabilities** — mark resources for a phase

Sandbox agents are marked with a small flask badge on their avatar wherever agents are listed.

## FAQ

<AccordionGroup>
  <Accordion title="Does turning on lifecycle phases change my running agents?">
    No. All agents become sandbox agents, but a sandbox agent is only restricted by resources you have explicitly
    marked production only and by a credit reserve above zero. Until you configure either, agents run exactly as
    before.
  </Accordion>

  <Accordion title="What happens to an agent that is demoted?">
    It immediately loses access to production-only capabilities, secrets, and API Capabilities, switches to sandbox
    secret values where they exist, and can only contact other sandbox agents. Nothing is deleted — promoting it again
    restores full access.
  </Accordion>

  <Accordion title="Can I define more phases than sandbox and production?">
    Not in the current release. Two phases cover the common case of separating testing from live operation.
  </Accordion>
</AccordionGroup>

## Learn more

<CardGroup cols={3}>
  <Card title="Agent management" icon="sliders" href="/features/agent-management">
    Filter agents by phase and change phases in bulk
  </Card>

  <Card title="Credentials" icon="key" href="/security/credentials">
    How secrets are stored and protected
  </Card>

  <Card title="Multi-agent systems" icon="diagram-project" href="/features/multi-agent">
    Agent-to-agent communication and delegation
  </Card>
</CardGroup>