# 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 start in `idle` status; no work happens until you send an event.
```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.
## Optional fields
- `title` — human-readable label
- `vault_ids` — credentials for MCP servers; see [[Claude Managed Agents Tools]] and vaults
- `resources` — attach [[Claude Managed Agents Memory Stores|memory stores]] (research preview)
## 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` | Unrecoverable error; session is dead |
Status transitions are surfaced on the event stream (`session.status_idle`, `session.status_running`).
## 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` | Enumerate org sessions |
| `archive` | Prevent new events while keeping history |
| `delete` | Remove session, events, and container (must not be `running` — interrupt first) |
Agents, environments, memory stores, and files are **independent resources**; deleting a session doesn't touch them.
## 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
## Related
- [[Claude Managed Agents]]
- [[Claude Managed Agents Events]]
- [[Claude Managed Agents Environments]]