claude-managed-agents

Claude Managed Agents

Managed Agents is Anthropic's hosted infrastructure for running Claude as an autonomous agent. Instead of building your own agent loop, you get a cloud container where Claude can run bash, read/write files, search the web, and execute code — all managed by Anthropic. Built-in prompt caching, context compaction, and performance optimizations are included.

Official API documentation (always up to date):

• Overview & concepts: https://platform.claude.com/docs/en/managed-agents/overview
• Quickstart: https://platform.claude.com/docs/en/managed-agents/quickstart
• API reference: https://platform.claude.com/docs/en/managed-agents/api-reference
• Events reference: https://platform.claude.com/docs/en/managed-agents/events

If you need the latest details on any endpoint, parameter, or behavior not covered in this skill's reference files, fetch the relevant documentation page above.

Beta header required on every request:

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

The SDK sets this automatically. Raw HTTP calls must include it manually.

The 4 Core Concepts

Agent       → reusable config: model + system prompt + tools + skills
Environment → reusable container template: packages + networking
Session     → live running instance of Agent inside Environment
Events      → the communication layer: you send events in, agent sends events out

Create Agent and Environment once. Reuse them across many Sessions. Each session gets its own isolated container — no shared filesystem between sessions.

Setup

pip install anthropic          # Python
npm install @anthropic-ai/sdk  # TypeScript

from anthropic import Anthropic
client = Anthropic()  # uses ANTHROPIC_API_KEY env var

ant CLI — Anthropic's official CLI for interactive agent/environment/session management. Install: brew install anthropics/tap/ant (macOS) or download from GitHub releases. The Python/TS SDK is sufficient for application code.

Step 1 — Create an Agent

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-sonnet-4-6",          # claude-opus-4-6 or claude-haiku-4-5 also valid
    system="You are a helpful coding assistant. Write clean, well-documented code.",
    tools=[{"type": "agent_toolset_20260401"}],  # enables all 8 built-in tools
)
# Save agent.id — you'll reference it in every session

Agent fields:

| Field | Notes | |---|---| | model | Required. All Claude 4.5+ models. Fast mode: {"id": "claude-opus-4-6", "speed": "fast"} | | system | Agent persona/behavior. Distinct from user messages (which describe the task). | | tools | agent_toolset_20260401 = all built-in tools. See references/tools.md for fine-grained control. | | skills | Anthropic pre-built: xlsx, pdf, docx, pptx. Or custom skills by ID. Max 20/session. | | callable_agents | Research preview. Other agent IDs this agent can delegate to. | | metadata | Arbitrary key-value pairs for your own tracking. |

Attaching skills:

agent = client.beta.agents.create(
    name="Financial Analyst",
    model="claude-sonnet-4-6",
    system="You are a financial analysis agent.",
    skills=[
        {"type": "anthropic", "skill_id": "xlsx"},               # Anthropic pre-built
        {"type": "custom", "skill_id": "skill_abc123", "version": "latest"},  # your own
    ],
)

Versioning: Every update() call increments version. Always pass the current version back:

agent = client.beta.agents.update(agent.id, version=agent.version, system="new prompt")

Omitted fields are preserved. Arrays (tools, skills) are fully replaced on update. Archive = read-only.

Step 2 — Create an Environment

environment = client.beta.environments.create(
    name="my-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},  # or "limited" — see below
        "packages": {
            "pip": ["pandas", "numpy", "requests"],
            "npm": ["express"],
            "apt": ["ffmpeg"],
        },
    },
)
# Save environment.id

Networking modes:

• unrestricted — full outbound access (fine for dev)
• limited — allowlist only (recommended for production)

# Production-safe networking
"networking": {
    "type": "limited",
    "allowed_hosts": ["api.example.com", "storage.googleapis.com"],
    "allow_mcp_servers": True,       # lets MCP server endpoints through
    "allow_package_managers": True   # lets pip/npm registries through at runtime
}

Supported package managers: apt, cargo, gem, go, npm, pip Packages declared here are cached across all sessions sharing this environment.

For container specs, pre-installed runtimes, and filesystem layout, see references/container-reference.md.

Step 3 — Create a Session

session = client.beta.sessions.create(
    agent=agent.id,                # uses latest version
    # agent={"type": "agent", "id": agent.id, "version": 2},  # pin a specific version
    environment_id=environment.id,
    title="My task",               # optional, human-readable label
    vault_ids=["vault_abc"],       # optional — attach vaults for MCP auth credentials
    resources=[                    # optional file/repo mounts
        {
            "type": "github_repository",
            "url": "https://github.com/org/repo",
            "authorization_token": "ghp_...",
            "checkout": {"type": "branch", "name": "main"},
            "mount_path": "/repo",
        },
        {"type": "file", "file_id": "file_abc123", "mount_path": "/data/input.csv"},
    ],
)
# Save session.id

Session statuses:

| Status | Meaning | |---|---| | idle | Waiting for input, or between turns | | running | Actively processing | | rescheduling | Transient error; auto-retry in progress | | terminated | Unrecoverable error — stop your loop |

Important: You cannot delete a running session — interrupt first, then delete. Files, environments, and agents are NOT deleted when a session is deleted — only the session history and container are gone. Use archive to preserve history in read-only form.

For MCP setup with vaults, see references/vaults-and-mcp.md. For session CRUD, usage/stats, and mid-session resource management, see references/session-management.md. For production patterns, cost monitoring, debugging, and testing strategies, see references/production-patterns.md.

Step 4 — The Event Loop

Open the stream first, then send the message. If you send before opening, the API buffers events and you may miss the start. In Python, always open the stream first to eliminate any race conditions.

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text", "text": "Write a fibonacci script and test it"}],
        }],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="", flush=True)

            case "agent.tool_use":
                print(f"\n[{event.name}]", flush=True)

            case "agent.custom_tool_use":
                # You must execute this and send back the result — agent is waiting
                result = my_execute_tool(event.name, event.input)
                client.beta.sessions.events.send(session.id, events=[{
                    "type": "user.custom_tool_result",
                    "custom_tool_use_id": event.id,
                    "content": [{"type": "text", "text": str(result)}],
                    "is_error": False,
                }])

            case "session.status_idle":
                # Could be done, or could need your input — always check stop_reason
                break