Claude Managed Agents: agents, environments, sessions
Claude Managed Agents is a hosted agent harness: Anthropic runs the agent loop and the sandbox where Claude reads files, runs commands and searches the web. You create an agent once, then start a session for each run that references that agent by id. It is in beta and needs the managed-agents-2026-04-01 header, which the SDK sets for you.
The four concepts
Agent: the model, system prompt, tools, MCP servers and skills. Environment: where sessions run, either an Anthropic-managed cloud sandbox or a self-hosted sandbox. Session: a running agent instance doing one task. Events: the messages between your app and the agent, such as user turns, tool results and status updates.
You send a user.message event, Claude runs tools on its own, and results stream back over server-sent events. Event history is stored server-side. You can send more events to steer the agent or interrupt it. The Messages API suits custom loops and fine control; Managed Agents suits long-running and asynchronous work.
Create the agent once
An agent is a reusable, versioned configuration. Create it once, for example with client.beta.agents.create(...), and pass its id to sessions.create for every run. Its version starts at 1 and increments each time an update changes it. Passing only the id starts the session on the latest version; passing {"type": "agent", "id": ..., "version": 1} pins a version.
A session can also use {"type": "agent_with_overrides", ...} to replace model, system, tools, mcp_servers or skills for that session only. Overrides replace a field in full and do not change the agent. Clearing tools returns a 400 while the session still has skills, because skills need the read tool.
Starting work
A session needs an agent id and an environment id. Creating it without initial_events starts no work, but the sandbox begins provisioning at once, so the first tool call does not wait on it. A non-empty initial_events list starts the agent in the same call.
Where the exam catches people
Calling agents.create() on every request is wrong: the agent is a persistent, versioned object you create once and reference by id.
The Tool Runner and a manual Messages API loop do not host a sandbox; Managed Agents is the option where Anthropic runs both the loop and the workspace.
Creating a session early is not wasted: the sandbox starts provisioning at creation, before the first event.
A session override does not merge with the agent's settings; it replaces that field in full for that session.