> ## 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 finished work, including the lifecycle and how credentials reach the agent. 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, or status change. | Events are append-only and can be listed, streamed, and resumed from any point. | | **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, and you can preview and download them. | | **File** | An upload you attach read-only to sessions. | A session keeps the content it attached, even if the file changes later. | | **Automation** | A pinned agent version, environment, prompt, and run defaults, started by a schedule, a Slack or GitHub event, or by hand. | Every run records exactly what it was given and the session it started. | See the [Glossary](/recursion/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. [Sessions](/recursion/sessions#how-a-session-runs) lists every state and what moves a session between them. What each state tells you: * **queued**: The session is waiting to start, because the agent already has as many root sessions running as its `max_concurrent_sessions` allows or because no sandbox capacity is free yet. 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`, `interrupted`, `requires_action`, `out_of_credit`, `error`, and others. When the agent finishes its work, `stop_reason` is `end_turn` and `status` becomes `completed`. An idle session keeps its sandbox until the environment's idle policy stops it. * **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](/recursion/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. 6. You read the transcript, the deliverables, 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. | 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](/recursion/vaults) and [Security](/recursion/security). ## 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. Subagents and teammates share their root session's sandbox and hand work over by file path. See [Artifacts](/recursion/artifacts) and [Multi-agent](/recursion/multi-agent). ## Next steps Run the whole flow once: key, environment, agent, 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.