Claude Managed Agents separate “behavior definition” (Agent) and “execution environment definition” (Environment) into create-once resources. Each task only needs a Session to combine them, and the orchestration loop plus state management are all handled server-side by Anthropic.

Explanation

An Agent stores the model, system prompt, tools, and MCPs. An Environment stores the sandbox template (packages, networking). Both are create-once / reuse-by-ID resources. A Session is the runtime instance of Agent + Environment – the server side runs the tool call loop, persists conversation history and sandbox filesystem. Your app only needs to subscribe to the event stream or webhook; you do not need to write your own agent loop. This design decouples “what Claude should do” from “where it runs,” similar to how K8s separates Deployment spec from Node/namespace management.

Knowledge Sugar

Comparison with self-managed: when you build an agent yourself with the Messages API, you maintain the messages[] array, set up sandboxes, write error recovery, and manage context window overflow. Managed Agents offload all of this infra – you go from “the person writing the loop” to “the person subscribing to results.”

Docker analogy: Environment is like a Docker image; each Session’s sandbox is like running docker run from that image. Sessions start fresh between each other, but within a Session things are stateful (filesystem + conversation history persist).

Agent versioning: the Agent config is a versioned resource. You can pin a session to a specific version for staged rollout without always running the latest.

Event types: events produced by a Session follow the sequence thinking, tool_use, tool_result. When the task finishes naturally, it emits session.status_idle. A Session can receive multiple rounds of events – it is not one-shot.

Multi-agent gotcha: in a multi-agent session, all agents share the same sandbox filesystem (agents can pass intermediate artifacts via files), but conversation context is isolated per-agent thread. The isolation boundary is context, not filesystem.