Agent lifecycle phases

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.

​

The two phases

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 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.

​

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 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

​

Learn more