CONCEPT The one distinction that matters
Everything in Cluster 4 so far assumed you host the agent loop — you call POST /v1/messages,
inspect stop_reason, run tools, and append tool_results. That's the
self-orchestrated model ("Claude API + tool use"). Managed Agents flip the
hosting: Anthropic hosts the agent loop and a per-session container
where tools execute. You describe the agent once; Anthropic runs it.
CONCEPT The Managed Agents shape
Conceptually there are two objects:
- Agent — a persisted, versioned object that holds the configuration: model, system prompt, and tools live on the Agent. You create it once; it's referenced by id.
- Session — a run that references an Agent by id. Each session gets its own per-session container where tools execute. The agent loop runs inside Anthropic's infrastructure.
CONCEPT Side-by-side
| Aspect | Self-orchestrated (Claude API + tool use) | Managed Agents |
|---|---|---|
| Who runs the loop | You (your code drives the loop) | Anthropic hosts the loop |
| Where tools execute | Your infrastructure | An Anthropic-hosted per-session container |
| Config location | In your code each call | On a persisted, versioned Agent object |
| How you run it | Call POST /v1/messages in a loop | Create a Session that references the Agent by id |
| Control vs. convenience | Maximum control & flexibility | Less to build/operate; Anthropic manages the loop & container |
DIAGRAM Where the loop lives
loop + tool execution"] <-->|POST /v1/messages| API1["Claude API"] end subgraph MAN["Managed Agents — Anthropic hosts"] direction LR AG["📄 Agent (persisted, versioned)
model · system · tools"] --> SESS["Session (references Agent by id)"] SESS --> HOST["Anthropic-hosted loop
+ per-session container (tools run here)"] end classDef y fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; classDef a fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b; class YC y; class AG a; class SESS a; class HOST a;
TRADE-OFFS Control vs. managed convenience
✅ Self-orchestrated
- Full control over the loop and tool execution
- Runs on your infrastructure, your environment
- Maximum flexibility for custom orchestration
✅ Managed Agents
- Anthropic hosts the loop + per-session container
- Config lives on a persisted, versioned Agent
- Less to build and operate yourself
EXAM TRAPS
PRACTICE
Q1 · In one sentence, what's the core difference between Managed Agents and "Claude API + tool use"?
In Managed Agents, Anthropic hosts the agent loop and a per-session container where tools run; with "Claude API + tool use," you host the loop and execute the tools yourself.
Q2 · Where do a Managed Agent's model, system prompt, and tools live?
On the persisted, versioned Agent object. You create the Agent once, then create Sessions that reference it by id to run it.
Q3 · A team wants Anthropic to run the loop and provide a container for tool execution. Which option?
Managed Agents. That's exactly the hosted-loop + per-session-container model, versus self-hosting the loop with the plain Claude API + tool use.