# Claude Managed Agents Sessions A **session** is a running instance of a [[Claude Managed Agents|managed agent]] inside an environment. It is the unit of work; events flow in and out of a session, conversation history is persisted, and the container lives for the session's lifetime. ## Creating a session Required: `agent` ID and `environment_id`. Sessions created without `initial_events` start in `idle`; no work happens until you send an event (the sandbox starts provisioning right away, though, so the first tool call doesn't wait). ```python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, title="Quickstart session", ) ``` Pin to a specific agent version (otherwise latest is used): ```python session = client.beta.sessions.create( agent={"type": "agent", "id": agent.id, "version": 1}, environment_id=environment.id, ) ``` Pinning versions lets you stage rollouts: old sessions keep running on v1 while new ones pick up v2. ### Create and start in one call `initial_events` (up to 50 `user.message` and/or one `user.define_outcome` event) creates the session directly in `running`. Validation is all-or-nothing. A request body over 32 MB returns 413. ### Per-session overrides Pass `agent` as `{"type": "agent_with_overrides", "id": ..., "version": ...}` plus any of `model`, `system`, `tools`, `mcp_servers` or `skills` to change the config for one session without versioning the agent (try another model, grant an extra tool). A `model` override replaces the whole model object, including its `inference_geo` pin. ## Optional fields - `title`: human-readable label - `vault_ids`: MCP credentials and environment-variable secrets from vaults; see [[Claude Managed Agents]] (vaults section) and [[Claude Managed Agents Tools]] - `resources`: attach [[Claude Managed Agents Memory Stores|memory stores]] (public beta; up to 8 per session), files, or a GitHub repository - `budget`: hard spend ceiling at list prices, e.g. `{"type": "limit", "max_list_cost": {"amount": "2500", "currency": "USD"}}` for $25. At the cap the session pauses idle with `budget_reached`. Can only be attached at creation; later you can raise, lower (above what's already spent) or remove it, and either resumes the work ## Session statuses | Status | Meaning | |---|---| | `idle` | Waiting for user input or tool confirmation; sessions start here | | `running` | Agent is actively thinking or executing tools | | `rescheduling` | Transient error, auto-retrying | | `terminated` | Ended by an unrecoverable error or by archiving. A session that finishes its work goes `idle`, not `terminated` | Status transitions are surfaced on the event stream (`session.status_running`, `session.status_idle`, `session.status_rescheduled`, `session.status_terminated`). Only runtime in `running` is billed ($0.08 per session-hour). Conversation history persists until you delete the session, but the sandbox state (files, installed packages) is only kept for 30 days after the sandbox is created, whatever the activity; after that, a resumed session starts from a fresh sandbox. ## Driving a session Send events with `sessions.events.send()`; stream responses with `sessions.events.stream()`. A session is a state machine: events drive execution; the session tracks progress. See [[Claude Managed Agents Events]] for the full event model. ## Operations | Op | Effect | |---|---| | `retrieve` | Fetch current status, config, outcomes | | `list` | Paginated (`limit`, `page` cursor, `order` asc/desc, newest first by default) | | `update` | Change `agent.tools` and `agent.mcp_servers` mid-session (full replacement, session-local, session must be `idle`); or the budget | | `archive` | Prevent new events while keeping history (not while `running`: interrupt first) | | `delete` | Remove session, events, and sandbox (not while `running`: interrupt first) | Agents, environments, memory stores, vaults, skills and uploaded files are **independent resources**; deleting a session doesn't touch them. Files the session itself produced ARE deleted with it, so download outputs first. Sessions can also be started on a cron schedule by a scheduled deployment (see [[Claude Managed Agents]]). ## References - Sessions: https://platform.claude.com/docs/en/managed-agents/sessions - Events and streaming: https://platform.claude.com/docs/en/managed-agents/events-and-streaming - Session operations: https://platform.claude.com/docs/en/managed-agents/session-operations - Session budgets: https://platform.claude.com/docs/en/managed-agents/budgets - Pricing (session runtime): https://platform.claude.com/docs/en/about-claude/pricing#claude-managed-agents-pricing ## Related - [[Claude Managed Agents]] - [[Claude Managed Agents Events]] - [[Claude Managed Agents Environments]]