Managed Agents provisions a container per session as the agent's workspace.
Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's tools execute — bash commands, file operations, code. You create a persisted Agent config (model, system prompt, tools, MCP servers, skills), then start Sessions that reference it. The session streams events back to you; you send user messages and tool results in.
Why agents are separate objects: versioning. An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you agents.create() fresh on every run.
Every session references a pre-created /v1/agents object. Create the agent once, store the ID, and reuse it across runs.
| Step | Call | Frequency | |---|---|---| | 1 | POST /v1/agents — model, system, tools, mcp_servers, skills live here | ONCE. Store agent.id and agent.version. | | 2 | POST /v1/sessions — agent: "agent_abc123" or {type: "agent", id, version} | Every run. String shorthand uses latest version. |
If you're about to write sessions.create() with model, system, or tools on the session body — stop. Those fields live on agents.create(). The session takes a pointer only.
When generating code, separate setup from runtime. agents.create() belongs in a setup script (or a guarded if agent_id is None: block), not at the top of the hot path. If the user's code calls agents.create() on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: define the agent as a version-controlled YAML manifest, apply it once with ant beta:agents create < agent.yaml (or a guarded setup script — see shared/anthropic-cli.md), persist the returned ID (config file, env var, secrets manager), and have every run load the ID and call sessions.create().
To change the agent's behavior, use POST /v1/agents/{id} — don't create a new one. Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via {type: "agent", id, version}). See shared/managed-agents-core.md → Agents → Versioning. To change tools/mcp_servers on one running session without touching the agent object, use sessions.update() (vault_ids attaches at session create only) — see shared/managed-agents-core.md → Updating the agent configuration mid-session.
Managed Agents is in beta. The SDK sets required beta headers automatically:
| Beta Header | What it enables | | ------------------------------ | ---------------------------------------------------- | | managed-agents-2026-04-01 | Agents, Environments, Sessions, Events, Session Resources, Session Threads, Outcomes, Multiagent, Vaults, Credentials, Memory Stores, Deployments | | skills-2025-10-02 | Skills API (for managing custom skill definitions) | | files-api-2025-04-14 | Files API for file uploads |
Which beta header goes where: The SDK sets managed-agents-2026-04-01 automatically on client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}. calls, and files-api-2025-04-14 / skills-2025-10-02 automatically on client.beta.files. / client.beta.skills.* calls. You do NOT need to add the Skills or Files beta header when calling Managed Agents endpoints. On raw HTTP the Managed Agents header grants Files API access on its own, so uploading a file for use as a session resource does not need files-api-2025-04-14 alongside it. (Direct Skills API calls over cURL do still need skills-2025-10-02; the ant CLI and the SDKs send it for you.) Exception — session-scoped file listing: client.beta.files.list({scope_id: session.id}) is a Files endpoint that takes a Managed Agents parameter, so it needs both headers. Pass betas: ["managed-agents-2026-04-01"] explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See shared/managed-agents-environments.md → Session outputs.
| User wants to... | Read these files | | -------------------------------------- | ------------------------------------------------------- | | Get started from scratch / "help me set up an agent" | shared/managed-agents-onboarding.md — guided interview (WHERE→WHO→WHAT→WATCH), then emit code | | Understand how the API works | shared/managed-agents-core.md | | See the full endpoint reference | shared/managed-agents-api-reference.md | | Create an agent (required first step) | shared/managed-agents-core.md (Agents section) + language file | | Update/version an agent | shared/managed-agents-core.md (Agents → Versioning) — update, don't re-create | | Create a session | shared/managed-agents-core.md + {lang}/managed-agents/README.md (cURL/C#: curl/managed-agents.md) | | Configure tools and permissions | shared/managed-agents-tools.md | | Set up MCP servers | shared/managed-agents-tools.md (MCP Servers section) | | Stream events / handle tool_use | shared/managed-agents-events.md + language file | | Get notified of session state changes via webhook (no polling) | shared/managed-agents-webhooks.md — Console-registered endpoint, HMAC verify, thin payload + fetch | | Define an outcome / rubric-graded iterate loop | shared/managed-agents-outcomes.md — user.define_outcome event, grader, span.outcome_evaluation_* events | | Coordinate multiple agents / subagents / threads | shared/managed-agents-multiagent.md — multiagent: {type: "coordinator", agents: [...]} on the agent, session threads, cross-posted tool confirmations | | Set up environments | shared/managed-agents-environments.md + language file | | Run tool execution in your own infra / VPC (self-hosted sandbox) | shared/managed-agents-self-hosted-sandboxes.md — config:{type:"self_hosted"}, ANTHROPIC_ENVIRONMENT_KEY, EnvironmentWorker.run() / ant beta:worker poll | | Upload files / attach repos | shared/managed-agents-environments.md (Resources) | | Give agents persistent memory across sessions | shared/managed-agents-memory.md — memory stores, memory_store session resource, preconditions, versions/redact | | Define agents/environments as version-controlled YAML; drive the API from the shell | shared/anthropic-cli.md — ant beta:agents create < agent.yaml, --transform, @file inlining | | Store credentials (MCP auth, API keys for CLIs/SDKs) | shared/managed-agents-tools.md (Vaults section) — mcp_oauth / static_bearer / environment_variable | | Call a non-MCP API / CLI that needs a secret | shared/managed-agents-tools.md (Vaults section) — environment_variable credential, substituted at egress. If that doesn't fit (e.g. self-hosted sandboxes), shared/managed-agents-client-patterns.md Pattern 9 keeps the secret host-side via a custom tool | | Run an agent on a recurring cron schedule | shared/managed-agents-scheduled-deployments.md — deployments, deployment runs, pause/auto-pause | | Cap a session's spend with a hard dollar budget | shared/managed-agents-core.md (§ Session budgets) — budget at session create, budget_reached pause, change/remove to resume. Deployments: shared/managed-agents-scheduled-deployments.md § Deployment budgets | | Pin where model inference runs (data residency) | shared/managed-agents-core.md (§ Pinning inference geography) — model.inference_geo on the agent, per-session override, roster uniformity | | Load skills from the codebase instead of uploading | shared/managed-agents-tools.md (§ Skills from a GitHub repository) — root .claude/skills discovery at session start | | Give the session an advisor to consult mid-turn | shared/managed-agents-multiagent.md (§ Advisor) — {type: "advisor", model} roster entry, consultation threads, plaintext vs redacted delivery |
agent field accepts only a string ID or {type: "agent", id, version}. model, system, tools, mcp_servers, skills are top-level fields on POST /v1/agents, never on sessions.create(). If the user hasn't created an agent, that is step zero of every example.agents.create() is a setup step. Store the returned agent_id and reuse it; don't call agents.create() at the top of your hot path. If the agent's config needs to change, POST /v1/agents/{id} — each update creates a new version, and sessions can pin to a specific version for reproducibility.mcp_servers array declares {type, name, url} only (no auth). Credentials live in vaults (client.beta.vaults.credentials.create) and attach to sessions via vault_ids. Anthropic auto-refreshes OAuth tokens using the stored refresh token. Vaults also hold environment_variable credentials for non-MCP services (CLIs, SDKs, direct API calls) — substituted at egress, never visible in the sandbox.shared/managed-agents-onboarding.md → §3 Pre-flight viability check.GET /v1/sessions/{id}/events/stream is the primary way to receive agent output in real-time.agent.tool_use, agent.mcp_tool_use, or agent.custom_tool_use is pending resolution (user.tool_confirmation for the first two, user.custom_tool_result for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with GET /v1/sessions/{id}/events/stream , fetch GET /v1/sessions/{id}/events, dedupe by event ID, then proceed. See shared/managed-agents-events.md → Reconnecting after a dropped stream.requests timeout=(c, r) and httpx.Timeout(n) are per-chunk read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track time.monotonic() at the loop level and bail explicitly. Prefer the SDK's sessions.events.stream() / sessions.events.list() over hand-rolled HTTP. See shared/managed-agents-events.md → Receiving Events.running or idle; they're processed in order. No need to wait for a response before sending the next message. Exception: a session paused at its budget (stop_reason: budget_reached) accepts only settle events — change or remove the budget to resume (shared/managed-agents-core.md § Session budgets).config.type is "cloud" or "self_hosted" — cloud runs the container on Anthropic's infrastructure; self_hosted moves tool execution to your own (see shared/managed-agents-self-hosted-sandboxes.md)..archive() on a production agent, environment, or memory store as cleanup — always confirm with the user before archiving.