Claude Managed Agents — Cheat Sheet

Managed Agents in one sentence

Claude Managed Agents is Anthropic's hosted harness: you define an Agent config once, run it in a managed sandbox (Environment), and start stateful Sessions that stream Events back to your app — bash, files, web search, and MCP without you building the loop.

Beta as of 2026 — verify current docs at platform.claude.com/docs/en/managed-agents/overview before production.

Messages API vs Managed Agents

	Messages API	Managed Agents
Control	You own the agent loop	Anthropic owns orchestration
Runtime	Your server	Managed cloud sandbox (or self-hosted env)
Best for	Chat, custom tools, tight control	Long jobs, async work, persisted filesystem
State	You persist	Sessions + container filesystem

Pick Managed Agents when a task runs minutes to hours with many tool calls and you do not want to maintain sandboxes.

Four objects to memorize

Agent (POST /v1/agents)

Versioned config: model, system prompt, tools, MCP servers, skills. Create before any session. Sessions reference agent_id (+ optional pinned version).

Environment (POST /v1/environments)

Template for where tools execute — Anthropic-managed container or your self-hosted sandbox. Defines packages, mounts, network policy.

Session (POST /v1/sessions)

Running instance: agent + environment + initial user instruction. Produces an event stream until idle.

Events (stream)

User messages, assistant messages, tool calls/results, status (status_idle when done). Your app subscribes and reacts.

API headers (manual HTTP)

Managed Agents endpoints require beta header:

anthropic-beta: managed-agents-2026-04-01

Memory store endpoints use agent-memory-2026-07-22. Official SDKs attach the correct header automatically.

Minimal Python flow (conceptual)

import anthropic

client = anthropic.Anthropic()

# 1. Create agent
agent = client.agents.create(
    name="ops-researcher",
    model="claude-sonnet-4-20250514",
    system="You are a careful research assistant. Cite sources.",
    tools=[{"type": "agent_toolset_20260401"}],
)

# 2. Create environment
env = client.environments.create(
    name="default-sandbox",
    # provider-specific fields — see quickstart
)

# 3. Start session
session = client.sessions.create(
    agent_id=agent.id,
    environment_id=env.id,
    initial_message="Summarize our Q2 metrics CSV in /workspace/data.csv",
)

# 4. Stream events
with client.sessions.stream_events(session.id) as stream:
    for event in stream:
        print(event.type, event)

Exact SDK method names may differ by version — treat as pattern, not copy-paste gospel.

Tooling included in agent_toolset

Typical built-ins (confirm in docs):

• Bash in sandbox
• Read/write files under mounted workspace
• Web search / fetch (policy-dependent)
• Code execution helpers

Attach MCP servers on the Agent object for proprietary integrations (CRM, internal APIs).

Session lifecycle

create agent (once)
    → create environment (once per sandbox profile)
        → start session per task
            → send user events
            → receive tool + message events
            → idle → fetch outputs from /mnt/session/outputs or equivalent
            → close or start new session

Sessions are stateful — filesystem persists during the session. Do not treat them as stateless chat completions.

When to use Managed Agents

Good fits:

• Overnight report generation on uploaded files
• Multi-step research with web + files
• Data cleaning pipelines needing bash/python
• Scheduled cron jobs via platform schedulers

Poor fits:

• Sub-200ms chat UX (use Messages API)
• Multi-model routing (Claude only here)
• Ultra-tight cost control on bursty micro-prompts

Pricing and security

Hosted sessions bill session-hour infrastructure plus tokens — model one job before scaling. Security checklist:

• Sandbox network egress reviewed
• No production credentials in mounted files
• Agent system prompt includes data-handling rules
• Outputs scanned before auto-emailing clients
• Session logs retention understood
• Beta ToS re-read before client deliverables

Agent design tips

System prompt skeleton:

Role: [analyst / coder / ops]
Workspace: files under /workspace — read-only except /mnt/session/outputs
Process: plan → execute → write final artifacts to outputs
If blocked: emit status and stop — do not invent data

Pin agent.version in production so sessions do not drift when you update configs.

Quick reference table

Task	Endpoint
Define persona + tools	POST /v1/agents
Define sandbox	POST /v1/environments
Run work	POST /v1/sessions
Stream progress	GET /v1/sessions/{id}/events
Send follow-up	User event on session

---

MyGearHut library covers local agent stacks too — Claude Code From Zero, Hermes Agent Guide. Join The Gear Drop for hosted-vs-local decision frameworks.