Complete 2026 Setup Guide

All Platforms · All Operating Systems · Every Language SDK

Published April 2026  |  Public Beta  |  Official Anthropic API

What Is Claude Managed Agents?

Claude Managed Agents is Anthropic’s hosted infrastructure service, launched in public beta on April 8, 2026. It bundles the entire AI agent runtime — sandboxed code execution, state persistence, tool orchestration, error recovery, and context management — into a single REST API. Developers and businesses define what the agent should do; Anthropic runs everything underneath.

Prior to this launch, shipping a production AI agent required 3–6 months of infrastructure engineering before any agent logic could be written. That second job is now eliminated.

Before Managed Agents	After Managed Agents
Build your own sandbox & container	Secure cloud container provisioned automatically
Manage state & conversation history	Server-side persistent session + file system
Build agent loop & tool execution	Built-in loop — just send a message
Handle retries, errors, context overflow	Error recovery & context management built in
3–6 months to production	Working agent in under 30 minutes
Full engineering team required	Single developer or no-code setup

BETA: Beta status: All requests require the managed-agents-2026-04-01 beta header. The Python and TypeScript SDKs add this automatically. Certain features (outcomes, multiagent, memory) are in research preview — request separate access.

Core Concepts

The entire mental model of Managed Agents is: Agent → Environment → Session → Events.

Concept	Description	Reusable?
Agent	The static definition: model, system prompt, tools, MCP servers, and skills. Created once, reused across many sessions.	Yes
Environment	A cloud container template. Configures pre-installed packages (Python, Node.js, Go), network access rules, and mounted files.	Yes
Session	A live runtime instance combining one Agent + one Environment. Maintains file system and full event history throughout its life.	Per task
Events	Messages exchanged between your application and the session. Types: user.message, agent.message, agent.tool_use, agent.tool_result, session.status_idle.	Streamed live

Built-in Toolset (agent_toolset_20260401)

Using the toolset identifier agent_toolset_20260401 enables all pre-built tools at once. In production, enable only the subset your agent needs.

Tool	What It Does
Bash	Execute shell commands inside the container, including long-running processes
File Operations	Read, write, edit, glob, and grep files within the session file system
Web Search	Live search engine queries with structured results
Web Fetch	Retrieve full HTML or PDF content from any URL
MCP Servers	Connect to external tools via Model Context Protocol (GitHub, Slack, Notion, etc.)

Pricing

Managed Agents bills in two parts: runtime cost + Claude token cost.

Component	Rate	Example
Session runtime	$0.08 per session hour	Agent running 24/7 = ~$58/month in runtime
Claude tokens	Standard API model pricing	claude-sonnet-4-6 rates apply per token
Simple agent (<5 min tasks)	Runtime cost negligible	Token cost dominates
Long research agent (4–8 hrs)	Runtime can exceed token cost	Plan accordingly

COST TIP: Cost tip: Use claude-haiku-4-5 for simple sub-tasks and reserve claude-sonnet-4-6 or opus-4-6 for complex reasoning. A multi-agent pattern mixing models can cut token costs by 60–70%.

Prerequisites (All Platforms)

Before setting up on any operating system, complete these steps once.

1. Create an Anthropic account at console.anthropic.com (same login as claude.ai).
2. Generate an API key: Console → Settings → API Keys → Create Key. Copy and store it securely.
3. Ensure you are on a paid API plan. Free-tier accounts may have rate limits that prevent agent usage.
4. Confirm your organization has access: Managed Agents endpoints are rate-limited per organization. Tier-based limits also apply.

ACCESS: No waitlist — access is open to all API accounts in public beta. Start immediately with an existing API key at platform.claude.com/docs/en/managed-agents/quickstart.

Setup Guide: macOS

Step 1 — Install Python (if not already installed)

macOS ships with Python 3 on recent versions. Verify with:

python3 –version

If missing or below 3.8, install via Homebrew:

# Install Homebrew first (if needed) /bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)”   # Then install Python brew install python

Step 2 — Install Node.js (optional, for TypeScript SDK)

brew install node

Step 3 — Install the Anthropic Python SDK

pip3 install -U anthropic

Step 4 — Set Your API Key

For the current terminal session only:

export ANTHROPIC_API_KEY=’your-api-key-here’

To persist it across all terminal sessions, add to your shell profile:

# For Zsh (default on macOS Catalina+) echo ‘export ANTHROPIC_API_KEY=”your-api-key-here”‘ >> ~/.zshrc source ~/.zshrc   # For Bash echo ‘export ANTHROPIC_API_KEY=”your-api-key-here”‘ >> ~/.bash_profile source ~/.bash_profile

Step 5 — Verify Installation

python3 -c “import anthropic; print(anthropic.__version__)”

Step 6 — Run Your First Agent (Python)

from anthropic import Anthropic client = Anthropic()   # 1. Create agent agent = client.beta.agents.create(     name=’My First Agent’,     model=’claude-sonnet-4-6′,     system=’You are a helpful assistant.’,     tools=[{‘type’: ‘agent_toolset_20260401′}], ) print(f’Agent ID: {agent.id}’)   # 2. Create environment env = client.beta.environments.create(     name=’my-env’,     config={‘type’: ‘cloud’, ‘networking’: {‘type’: ‘unrestricted’}}, )   # 3. Create session session = client.beta.sessions.create(     agent=agent.id, environment_id=env.id, title=’First Session’ )   # 4. Send message and stream events 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’: ‘List the files in the current directory.’}]}]     )     for event in stream:         if event.type == ‘agent.message’:             for block in event.content:                 if block.type == ‘text’: print(block.text)         elif event.type == ‘session.status_idle’:             break

Setup Guide: Windows

Option A — Windows (Native PowerShell)

Step 1 — Install Python

Download Python 3.10 or later from python.org/downloads. During installation, check ‘Add Python to PATH’.

Verify in PowerShell:

python –version

Step 2 — Install the SDK

pip install -U anthropic

Step 3 — Set the API Key (PowerShell — current session)

$env:ANTHROPIC_API_KEY = “your-api-key-here”

To persist permanently (user-level, survives restarts):

[System.Environment]::SetEnvironmentVariable(“ANTHROPIC_API_KEY”, “your-api-key-here”, “User”)

Step 4 — Verify

python -c “import anthropic; print(anthropic.__version__)”

Option B — Windows Subsystem for Linux (WSL) — Recommended

WSL gives you a full Linux environment on Windows, which is the most compatible setup for Managed Agents development.

Step 1 — Install WSL

# Run in PowerShell as Administrator wsl –install # Restart your machine after installation completes

Step 2 — Open Ubuntu terminal and install Python & SDK

sudo apt update && sudo apt install -y python3 python3-pip pip3 install -U anthropic

Step 3 — Set API Key in WSL

echo ‘export ANTHROPIC_API_KEY=”your-api-key-here”‘ >> ~/.bashrc source ~/.bashrc

WINDOWS TIP: All Python and curl examples in this guide work identically in WSL. We recommend WSL for Windows developers as it matches the Linux environment where most Managed Agent tooling is tested.

Setup Guide: Linux (Ubuntu / Debian / RHEL / Arch)

Ubuntu / Debian

sudo apt update sudo apt install -y python3 python3-pip curl jq pip3 install -U anthropic echo ‘export ANTHROPIC_API_KEY=”your-api-key-here”‘ >> ~/.bashrc source ~/.bashrc

RHEL / Fedora / CentOS

sudo dnf install -y python3 python3-pip curl jq pip3 install -U anthropic echo ‘export ANTHROPIC_API_KEY=”your-api-key-here”‘ >> ~/.bashrc source ~/.bashrc

Arch Linux

sudo pacman -Syu python python-pip curl jq pip install -U anthropic echo ‘export ANTHROPIC_API_KEY=”your-key”‘ >> ~/.bashrc && source ~/.bashrc

TIP: jq is optional but highly recommended for parsing JSON responses when using curl directly. Install it on any system for easier debugging.

Setup Guide: TypeScript / Node.js (All Platforms)

Step 1 — Install Node.js

Download from nodejs.org. Verify:

node –version   # should be 18+ npm –version

Step 2 — Create Project and Install SDK

mkdir my-agent && cd my-agent npm init -y npm install @anthropic-ai/sdk npm install -D typescript ts-node @types/node

Step 3 — Set API Key

macOS / Linux:

export ANTHROPIC_API_KEY=”your-api-key-here”

Windows PowerShell:

$env:ANTHROPIC_API_KEY = “your-api-key-here”

Step 4 — TypeScript Agent Example (agent.ts)

import Anthropic from ‘@anthropic-ai/sdk’;   const client = new Anthropic();   async function main() {   // 1. Create agent   const agent = await client.beta.agents.create({     name: ‘TS Coding Assistant’,     model: ‘claude-sonnet-4-6’,     system: ‘You are a helpful coding assistant.’,     tools: [{ type: ‘agent_toolset_20260401’ }],   });   console.log(‘Agent ID:’, agent.id);     // 2. Create environment   const env = await client.beta.environments.create({     name: ‘ts-env’,     config: { type: ‘cloud’, networking: { type: ‘unrestricted’ } },   });     // 3. Create session   const session = await client.beta.sessions.create({     agent: agent.id,     environment_id: env.id,     title: ‘TS Quickstart’,   });     // 4. Stream events   const stream = await client.beta.sessions.events.stream(session.id);   await client.beta.sessions.events.send(session.id, {     events: [{ type: ‘user.message’, content: [{ type: ‘text’, text: ‘Write hello.py and run it.’ }] }]   });   for await (const event of stream) {     if (event.type === ‘agent.message’) {       for (const block of event.content) {         if (block.type === ‘text’) process.stdout.write(block.text);       }     }     if (event.type === ‘session.status_idle’) break;   } }   main().catch(console.error);

Step 5 — Run

npx ts-node agent.ts

Setup Guide: Raw REST API (curl — Any Platform)

Use curl if you want to test quickly, use a language without an official SDK, or inspect raw responses. curl works on macOS, Linux, and Windows (via WSL or Git Bash).

Step 1 — Set Environment Variable

export ANTHROPIC_API_KEY=”your-api-key-here”

Step 2 — Create Agent

curl -sS https://api.anthropic.com/v1/agents \   -H “x-api-key: $ANTHROPIC_API_KEY” \   -H “anthropic-version: 2023-06-01” \   -H “anthropic-beta: managed-agents-2026-04-01” \   -H “content-type: application/json” \   -d ‘{     “name”: “curl-agent”,     “model”: “claude-sonnet-4-6”,     “system”: “You are a helpful assistant.”,     “tools”: [{“type”: “agent_toolset_20260401”}]   }’ | jq -r ‘.id’

Step 3 — Create Environment

curl -sS https://api.anthropic.com/v1/environments \   -H “x-api-key: $ANTHROPIC_API_KEY” \   -H “anthropic-version: 2023-06-01” \   -H “anthropic-beta: managed-agents-2026-04-01” \   -H “content-type: application/json” \   -d ‘{“name”:”curl-env”,”config”:{“type”:”cloud”,”networking”:{“type”:”unrestricted”}}}’ | jq -r ‘.id’

Step 4 — Create Session

curl -sS https://api.anthropic.com/v1/sessions \   -H “x-api-key: $ANTHROPIC_API_KEY” \   -H “anthropic-version: 2023-06-01” \   -H “anthropic-beta: managed-agents-2026-04-01” \   -H “content-type: application/json” \   -d ‘{“agent”: “AGENT_ID”, “environment_id”: “ENV_ID”, “title”: “My session”}’ | jq -r ‘.id’

Step 5 — Send Message and Stream SSE Events

# Send user message (buffered until stream connects) curl -sS https://api.anthropic.com/v1/sessions/SESSION_ID/events \   -H “x-api-key: $ANTHROPIC_API_KEY” \   -H “anthropic-version: 2023-06-01” \   -H “anthropic-beta: managed-agents-2026-04-01” \   -H “content-type: application/json” \   -d ‘{“events”:[{“type”:”user.message”,”content”:[{“type”:”text”,”text”:”List files here.”}]}]}’ > /dev/null   # Open SSE stream and parse events curl -sS -N https://api.anthropic.com/v1/sessions/SESSION_ID/events/stream \   -H “x-api-key: $ANTHROPIC_API_KEY” \   -H “anthropic-version: 2023-06-01” \   -H “anthropic-beta: managed-agents-2026-04-01” | \ while IFS= read -r line; do   [[ $line == data:* ]] || continue   json=${line#data: }   case $(jq -r ‘.type’ <<<“$json”) in     agent.message) jq -j ‘.content[] | select(.type==”text”) | .text’ <<<“$json” ;;     agent.tool_use) printf ‘\n[Tool: %s]\n’ “$(jq -r ‘.name’ <<<“$json”)” ;;     session.status_idle) printf ‘\n\nDone.\n’; break ;;   esac done

Advanced: Environment Configuration

Environments are reusable container templates. Configure them once and reference the environment_id across many sessions.

Pre-installing Python Packages

env = client.beta.environments.create(     name=’data-science-env’,     config={         ‘type’: ‘cloud’,         ‘networking’: {‘type’: ‘unrestricted’},         ‘packages’: {             ‘pip’: [‘pandas’, ‘numpy’, ‘matplotlib’, ‘scikit-learn’, ‘pytest’, ‘black’]         }     } )

Restricted Network Mode

For security-sensitive tasks, use restricted networking to prevent data exfiltration:

env = client.beta.environments.create(     name=’secure-env’,     config={‘type’: ‘cloud’, ‘networking’: {‘type’: ‘restricted’}} )

Custom System Prompts with MCP Servers

agent = client.beta.agents.create(     name=’GitHub Agent’,     model=’claude-sonnet-4-6′,     system=’You are a code review specialist. Be precise and check for security issues.’,     tools=[{‘type’: ‘agent_toolset_20260401’}],     mcp_servers=[         {‘type’: ‘url’, ‘url’: ‘https://mcp.github.com/sse’, ‘name’: ‘github-mcp’}     ] )

SSE Event Types Reference

Claude Managed Agents uses Server-Sent Events (SSE) to stream results in real time. Handle each event type in your application:

Event Type	When It Fires	What to Do
user.message	You send a user message	Trigger by posting to /events endpoint
agent.message	Agent generates a text reply	Render incrementally to your UI
agent.tool_use	Agent is calling a tool	Show ‘agent is working’ indicator with tool name
agent.tool_result	Tool execution returns a result	Optionally display; useful for debugging
session.status_running	Agent is actively executing	Show loading indicator
session.status_idle	Agent finished all work	Close the stream; start next turn if needed

Real-World Use Cases & Starter Prompts

1. Code Review Agent

System prompt: You are a senior code reviewer. Analyze for bugs, security issues, and style violations. Return a structured report.

‘Review the Python file at /workspace/app.py and flag all critical issues.’

2. Document Processing Agent

System prompt: You are a document analyst. Extract structured data from files and return clean JSON.

‘Read the PDFs in /workspace/invoices/ and extract vendor name, amount, and date for each.’

3. Data Analysis Agent

System prompt: You are a data scientist. Write and run Python code to analyze data. Show results and visualizations.

‘Load sales.csv, compute monthly revenue trends, and save a summary report to output.md.’

4. Research & Summarization Agent

System prompt: You are a research analyst. Search the web, read sources, and produce factual summaries with citations.

‘Search for the latest developments in quantum computing this month and write a 500-word briefing.’

5. Customer Support First-Line Agent

System prompt: You answer customer support queries using the FAQ document at /workspace/faq.md. Escalate if the answer is not there.

‘A customer says: My order #48291 has not arrived after 10 days. What should I tell them?’

Agent Type	Best Model	Approx. Monthly Cost
Simple FAQ / Info lookups	claude-haiku-4-5	$5–20
Code review / bug fixing	claude-sonnet-4-6	$20–100
Deep research (multi-hour)	claude-opus-4-6	$100–400+
High-volume data pipelines	claude-haiku-4-5 (sub-tasks) + sonnet (planning)	$50–200

Managed Agents vs. Alternatives

Criteria	Managed Agents	Self-hosted (LangGraph)	Messages API
Time to first agent	~30 minutes	1–2 weeks	Hours (no sandbox)
Sandboxing	Built-in, hardened	DIY (Docker, gVisor)	None
Long-running sessions	Native (hours)	Redis + websocket DIY	Limited by context
Scaling	Auto-scales	You provision infra	Per-request
Vendor lock-in	High (Anthropic only)	Low (portable)	Medium
Customization	API surface only	Full control	Full control
Observability	Built-in tracing	DIY (Langfuse etc.)	DIY
Best for	Production speed, Claude-native stack	Multi-model, compliance	Real-time chat, granular control

Known Limitations (April 2026 Beta)

• No VPC peering or private endpoints — all traffic goes through Anthropic’s public infrastructure. Evaluate for strict data sovereignty requirements.
• Multiagent coordination, outcomes API, and memory are in research preview — expect instability before relying on them in production.
• No on-premise or self-hosted deployment option; execution is exclusively on Anthropic’s cloud infrastructure.
• Uptime commitments, SLAs, and enterprise support levels are beta-grade, not GA-grade.
• For long sessions (4–8+ hours), runtime cost ($0.08/hr) can exceed token cost — monitor this for always-on agents.
• Agent marketplace, custom tool registration, and regional deployments (EU/Asia) are on the roadmap but not yet live.

DECISION GUIDE: If your workload requires multi-cloud, full model portability, or on-premise execution, the Messages API or Agent SDK with self-hosting is the better fit right now. Choose Managed Agents when speed to production and Claude-native tooling matter most.

Troubleshooting

Error / Symptom	Likely Cause	Fix
400: missing beta header	Header not included	SDK handles automatically; for curl add: -H ‘anthropic-beta: managed-agents-2026-04-01’
401: invalid API key	Key wrong or unset	Check: echo $ANTHROPIC_API_KEY — must not be empty
403: rate limited	Org limit hit or wrong tier	Check console.anthropic.com → Usage. Upgrade tier if needed.
Session stays running forever	Agent waiting for input	Check event stream for session.status_idle or send an interrupt event
Tool calls not executing	Network restricted env	Switch networking to unrestricted or whitelist required domains
High token costs	Sending full history each turn	Use getEvents() to send only relevant slices of session history

Official Resources

• Quickstart Guide: platform.claude.com/docs/en/managed-agents/quickstart
• API Overview: platform.claude.com/docs/en/managed-agents/overview
• Agent SDK (Python/TypeScript): platform.claude.com/docs/en/agent-sdk/overview
• Anthropic Engineering Blog (architecture deep-dive): anthropic.com/engineering/managed-agents
• Python SDK GitHub: github.com/anthropics/claude-agent-sdk-python
• Discord Community: anthropic.com/discord
• Status Page: status.claude.com

© 2026 — Claude Managed Agents Complete Guide | Based on Anthropic official documentation