Managed Agents

Managed Agents

When to activate

Building applications where agents need to run autonomously in the cloud, or when the user mentions Claude Managed Agents, long-running agent tasks, or building agent-powered products via the Anthropic API.

When NOT to use

• Claude Code subagents running in a terminal session — those use the Task tool, not this API
• Short synchronous requests that complete in under 10 seconds — use the standard Messages API
• Workflows requiring Zero Data Retention (ZDR) or HIPAA BAA — Managed Agents are not eligible

Instructions

Core Concepts

• Agent: a configured entity with a model, system prompt, and allowed tool set
• Environment: a compute sandbox where the agent runs (cloud-hosted by Anthropic, or self-hosted)
• Session: one execution run — has a start, an end, and an event stream
• Events: Server-Sent Events (SSE) stream reporting what the agent is doing in real time

Key distinction from Claude Code subagents: Managed Agents run independently of your terminal in Anthropic's cloud. Use them for async, long-running, or API-driven agent products — not for Claude Code slash commands.

Beta Header

All Managed Agents API calls require:

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

Tool Type

To give an agent access to all built-in tools (Bash, file operations, web search, web fetch, MCP):

pythonCopy code
tools=[{"type": "agent_toolset_20260401"}]

Python Pattern

pythonCopy code
import anthropic

client = anthropic.Anthropic()

# 1. Create the agent (do once; reuse agent_id)
agent = client.beta.agents.create(
    model="claude-opus-4-5",
    name="research-agent",
    system="You are a research agent. When given a topic, search the web, gather facts, and produce a structured summary.",
    tools=[{"type": "agent_toolset_20260401"}],
)

# 2. Create an environment (cloud sandbox)
env = client.beta.environments.create(type="cloud")

# 3. Create a session and stream events
with client.beta.sessions.stream(
    agent_id=agent.id,
    environment_id=env.id,
    input="Research the latest developments in quantum computing and summarize in 3 bullet points.",
) as stream:
    for event in stream:
        if event.type == "agent.message":
            print(event.data.text, end="", flush=True)
        elif event.type == "agent.tool_use":
            print(f"\n[Tool: {event.data.name}]")
        elif event.type == "session.status_idle":
            print("\n[Session complete]")
            break

Event Types

Async Session (Fire and Poll)

For workloads where you don't want to hold a connection open:

pythonCopy code
# Start session without streaming
session = client.beta.sessions.create(
    agent_id=agent.id,
    environment_id=env.id,
    input="Analyze these 50 documents and extract action items.",
)
session_id = session.id

# Poll status later
import time
while True:
    session = client.beta.sessions.retrieve(session_id)
    if session.status in ("idle", "error"):
        break
    time.sleep(10)

# Retrieve output
output = client.beta.sessions.retrieve(session_id)
print(output.output)

Rate Limits

Testing with the ant CLI

bashCopy code
# Install
npm install -g @anthropic-ai/ant

# Test an agent interactively
ant run --agent-id <id> --environment cloud

# Run with a specific input
ant run --agent-id <id> --input "Summarize today's AI news"

Agent Lifecycle Management

• Agents are persistent configurations — create once, reuse across many sessions
• Environments are per-run compute sandboxes — create a new one per session for isolation
• Sessions are ephemeral — store the output before the session expires
• Store agent_id in your application config; store session output in your database

When to Use Cloud vs Self-Hosted Environment

• Cloud (type: "cloud"): fastest to start, no infrastructure, appropriate for most use cases
• Self-hosted: when the agent needs access to internal network resources, private data stores, or custom tool servers not reachable from Anthropic's cloud

Example

A product that lets users submit research tasks asynchronously via a web form:

1. User submits: "Find the top 5 competitors to our product and summarize their pricing"
2. App creates a session with type: "cloud" environment — stores session_id in the job queue
3. App returns immediately: "Your research report will be ready in ~10 minutes"
4. Background worker polls session status every 30 seconds
5. When session.status == "idle", worker retrieves session.output and emails the user
6. User receives a structured 5-competitor analysis with pricing tables

The entire agent run — web searches, data extraction, synthesis — happens in Anthropic's cloud with no infrastructure management.