Claude Managed Agents is a pre-built agent harness that runs on Anthropic's managed infrastructure: instead of building your own agent loop and tool runtime, you get an environment where Claude can read files, run commands, browse the web, and execute code, with conversation history and workspace state stored server-side. It is in beta, gated behind the managed-agents-2026-04-01 beta header (the SDK sets it automatically), and — critically for this site's audience — it is available only on the first-party Claude API and on Claude Platform on AWS. It is not supported on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.
Creating a session
A session is a stateful interaction that references two things you create ahead of time: an agent (a persisted, versioned configuration holding the model, system prompt, tools, MCP servers, and skills) and an environment (a template for the sandboxed container where tools execute). The mandatory flow is agent once, session every run. Session creation takes the agent reference and an environment_id, plus optional title, resources (files, GitHub repositories, memory stores), vault_ids for secrets, and metadata. Creating a fresh agent on every run is the documented number-one anti-pattern — it accumulates orphaned agents and defeats versioning.
from anthropic import AnthropicAWS
client = AnthropicAWS() # AWS_REGION + ANTHROPIC_AWS_WORKSPACE_ID
session = client.beta.sessions.create(
agent="agent_id_from_config", # created once, stored in config
environment_id="env_id_from_config",
title="quarterly-report-run",
)
# send work as an event, then consume the SSE stream
The lifecycle: rescheduling, running, idle, terminated
A session moves through four statuses: rescheduling → running ↔ idle → terminated. The one that surprises teams is idle: it does not mean something went wrong. It means the agent finished the current task and is waiting for input, with a stop_reason explaining why it stopped. A session can bounce between running and idle many times. terminated is irreversible. Errors never appear as a status — they surface as session.error events in the event stream, so a client that only watches status can miss failures entirely.
How "turns" actually work
There is no single-turn request/response call. You send events — most commonly user.message — and receive events back. Two properties matter operationally:
Messages queue server-side. You can send events while the session is running or idle; user messages are queued and processed in order, so you never need to wait for a response before sending the next instruction. If you need to jump the queue, a user.interrupt event goes ahead of pending messages and forces the session to idle — the agent halts without ever seeing the interrupt as a message.
You choose how to listen. There are three ways to receive output: a long-lived Server-Sent Events stream (GET /v1/sessions/{id}/events/stream), polling the paginated events list, or webhooks. The SSE stream has no replay — it only delivers events emitted after you connect — so on every reconnect you should overlap the stream with a history fetch and de-duplicate by event ID. Skipping this can deadlock a session that is waiting on a pending tool confirmation you never saw. Received events are dot-namespaced: agent.message, agent.thinking, agent.tool_use, session.status_idle, and so on.
What happens between turns
Between your messages, the harness does real work for you: automatic context compaction when the conversation nears the model's context limit, prompt caching of repeated historical tokens, and extended thinking on by default (returned as agent.thinking events). The container's filesystem persists across turns within the session, so files the agent wrote earlier remain available. Every session also has a live trace view in the Anthropic Console, which is the fastest way to debug a run that idled unexpectedly.
Closing, archiving, and deleting
Sessions do not simply expire into nothing; you manage their end of life explicitly. You can update only the title of an existing session. Archiving makes it read-only and is irreversible — routine cleanup for disposable sessions. Deleting permanently removes the session, its event history, its container, and checkpoints. Because sessions store conversation history and sandbox state server-side, Managed Agents is not currently eligible for zero-data-retention or HIPAA BAA coverage — but you can delete sessions and uploaded files at any time via the API. On cost: tokens bill at standard model rates, and session runtime bills at $0.08 per session-hour, metered to the millisecond only while the status is running — idle time is free.
Where to go next
Sessions run inside containers defined by agent environments, authenticate to external systems through vaults, and can notify your systems via webhooks. For the platform picture, see the feature matrix.