How it works

Managed Agents has a small set of building blocks. Once you know what each one is for and what it guarantees, every other page in these docs reads as a variation on the same flow.

​

The building blocks

See the Glossary for every other term.

​

The session lifecycle

A session has two fields that describe where it is. status is the coarse state, and execution_state says what the agent loop is doing right now. The diagram shows the execution_state values, plus the failed and cancelled values of status. What each state tells you:

• queued: The agent already has as many root sessions running as its max_concurrent_sessions allows. The session waits for a slot. Child sessions never count toward the cap.
• provisioning: The sandbox is being prepared. This normally takes under a minute. If compute isn’t ready within five minutes, the session fails with sandbox_provision_timeout.
• running: The agent or one of its tools is working.
• idle: Nothing is running. stop_reason says why: end_turn, sleeping, awaiting_subagents, outcome_unmet, max_iterations, interrupted, and others. An idle session keeps its sandbox until the environment’s idle policy stops it.
• completed: The work met its outcome. stop_reason is outcome_satisfied.
• failed and cancelled: The session stopped on an error or a hard stop. failure explains a failure.

A follow-up message starts a fresh turn on a stopped root session. Completed and failed sessions reuse their sandbox when it still exists. A hard stop tears the sandbox down, so a follow-up after one gets a new sandbox with a clean workspace. The full list of values is in Event types and states.

​

What happens when you start a session

1. You call startSession, or click Launch session in the console, with an agent, an environment, and a task. The request returns 202 Accepted right away with a session_id.
2. The session freezes the current agent version, the environment, and the credentials you granted.
3. The sandbox is provisioned and prepared with the environment’s verified setup, if it has a setup script. Session credentials are withheld from the setup script.
4. The agent works through model turns and tool calls. Each step is recorded as an event you can read or stream.
5. At the end of every turn, the agent’s deliverables are collected. If the session has an outcome, the grader runs next.
6. You read the transcript, the verdict, and the cost from the same session record.

​

How credentials reach the agent

Credentials never go in a prompt. You store them in a vault, or connect an app on the Integrations page, grant them to an agent or a session, and each type is delivered in its own way. Grant only what the task needs. A session can narrow its credentials to a list of specific items with credential_refs. Prefer an MCP credential whenever the service speaks MCP, because its value never enters the sandbox. See Vaults and Security.

​

How grading works

An outcome turns “the agent stopped” into “the work is done”. You give it an objective and a rubric of checkable criteria. After each turn, a separate grader scores every criterion. What you can rely on:

• The grader sees the objective, the rubric, and the agent’s work. It never sees a separate opening message, so you can give the agent context that isn’t part of what’s measured.
• Each criterion gets pass, fail, or not_applicable, with a rationale and the event ids it relied on.
• max_iterations caps grading passes. Omitted or 0 means the agent keeps revising until the grader is satisfied.
• A session has at most one open outcome at a time. Define the next one after the current one is graded.

See Outcomes for rubric writing and every result value.

​

Where the work happens

Each session tree gets its own sandbox. The agent’s working directory is /workspace. Agents already know where to save deliverables, so you only need to name the file you want in the task or the rubric. Subagents and teammates share their root session’s sandbox and hand work over by file path. See Artifacts and Multi-agent.

​

Next steps