> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # How it works > The concepts behind Managed Agents and how a session moves from start to a graded result, with diagrams of the lifecycle, credentials, and grading. 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 | Concept | What it is | Key guarantee | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | **Agent** | A reusable definition: model, system prompt, tools, skills, MCP servers, granted apps, and default credential grants. | Editing an agent never changes a session that already started. | | **Agent version** | One immutable snapshot of an agent. Every update publishes a new version. | A session runs exactly the version it started with. | | **Environment** | Where sessions run: the runtime, compute size, workspace disk, setup script, internet access, and idle policy. | A setup script must pass a verification run before sessions can use it. | | **Session** | One run of an agent version in an environment, working on a task. Child sessions share their root's sandbox. | Every step is recorded, and a stopped session can be continued with a follow-up message. | | **Event** | One recorded step: a message, tool call, tool result, status change, or grading pass. | Events are append-only and can be listed, streamed, and resumed from any point. | | **Outcome** | A definition of done: an objective plus a rubric of criteria. | A separate grader checks every criterion, and the agent revises until the work passes or hits its limit. | | **Vault** | A named group of credentials: MCP server tokens and environment-variable secrets. | Secret values are write-only and never returned by the API. | | **Integration** | Your organization's connection to an app, such as Zendesk or Snowflake, with the list of tools agents may use in it. | An agent reaches only the apps it's granted, and only the tools on each app's list. | | **Skill** | A reusable procedure in the Agent Skills format that an agent loads when it needs it. | Skills are snapshotted into the session at start. | | **Deliverable** | A file the agent saves as a result of its work. | Deliverables are collected at the end of every turn, before grading, and you can download them. | | **File** | An upload in your organization's library, attached read-only to sessions. | A session keeps the content it attached, even if the file changes later. | | **Memory** | Short documents an agent browses, searches, and reads: its learned memory from past sessions, plus curated stores you write. | Every change is a version you can review, restore, or redact. | | **Automation** | A saved agent version, environment, prompt, and run defaults, started by a schedule, an event, or by hand. | Every run records exactly what it was given and the session it started. | See the [Glossary](/managed-agents/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`. ```mermaid theme={"theme":"css-variables"} stateDiagram-v2 [*] --> queued: agent is at its session cap [*] --> provisioning: slot available queued --> provisioning: a slot frees provisioning --> running: sandbox ready provisioning --> failed: sandbox not ready in time running --> idle: turn ends idle --> running: follow-up message running --> completed: outcome satisfied running --> cancelled: hard stop running --> failed: unrecoverable error completed --> running: follow-up message failed --> running: follow-up message cancelled --> running: follow-up message ``` 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](/managed-agents/reference). ## 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. ```mermaid theme={"theme":"css-variables"} flowchart LR you["You"] -->|"store once"| vault["Vault"] you -->|"connect once, pick tools"| app["Integration"] vault -->|"granted to agent or session"| session["Session"] app -->|"granted to agent"| session session -->|"MCP token: attached outside the sandbox"| mcp["MCP server"] session -->|"environment-variable secret: set in the sandbox"| sandbox["Sandbox processes"] session -->|"short-lived access to allowed tools"| sandbox ``` | Credential | Where it goes | Can the agent read the value? | | --------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | MCP bearer token | Added to requests to the matching MCP server, outside the sandbox. | No. The model and the sandbox never receive it. | | Environment-variable secret | Set as an environment variable in the sandbox, under the name you choose. | Yes. Any command the agent runs can read and print it. | | Built-in integration access | Available to commands in the sandbox, renewed while the session runs. | Yes, but it works only for the granted apps and the tools on each app's list, and it expires within an hour. | 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](/managed-agents/vaults) and [Security](/managed-agents/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. ```mermaid theme={"theme":"css-variables"} flowchart TD work["Agent works a turn"] --> capture["Deliverables collected"] capture --> grade["Grader checks every criterion"] grade -->|"every criterion passes or does not apply"| satisfied["satisfied: session completed"] grade -->|"a criterion fails"| check{"Grading passes left?"} check -->|"yes"| feedback["Grader feedback sent to the agent"] feedback --> work check -->|"no"| capped["max_iterations_reached: session idle"] ``` 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](/managed-agents/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](/managed-agents/artifacts) and [Multi-agent](/managed-agents/multi-agent). ## Next steps Run the whole flow once: key, environment, agent, graded session. Choose the model, prompt, tools, skills, and credentials. Look up every start field and how to follow a session. See how sandboxes, network policy, and credentials are isolated.