April 10, 2026 · 14 min read

Claude Managed Agents: The Complete Getting Started Guide (2026)

On April 8, 2026, Anthropic launched Managed Agents in public beta — and it changes how developers build with Claude. Instead of wiring up your own agent loop with the Messages API, you now get a fully hosted agent runtime with container environments, built-in tools, and SSE streaming out of the box.

This guide walks through everything you need to go from zero to a working managed agent: core concepts, setup, code examples, pricing, and when to use it versus the raw Messages API.

1. What Are Claude Managed Agents?

Managed Agents are composable APIs for deploying cloud-hosted AI agents. Think of them as Claude-as-a-service with an agent harness built in. You define an agent (model, system prompt, tools), spin up a sandboxed environment, create a session, and send messages. Anthropic handles the agent loop, tool execution, and container lifecycle.

The key difference from the Messages API: with Messages, you build your own agent loop — you call the model, parse tool_use blocks, execute tools locally, and feed results back. With Managed Agents, that entire loop runs server-side in a managed container. You just send a message and stream events back.

2. Core Concepts

3. Getting Started

Step 1: Install the SDK

Choose your preferred method:

# CLI tool
brew install anthropics/tap/ant

# Python SDK (v1.x+ includes managed agents)
pip install anthropic

# Node.js / TypeScript SDK
npm install @anthropic-ai/sdk

Step 2: Create an Agent

An agent is your reusable config. You define it once and spin up sessions against it:

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-sonnet-4-6",
    system="You are a helpful coding assistant. Write clean, tested code.",
    tools=[{"type": "agent_toolset_20260401"}],
    # beta header is set automatically by the SDK
)

print(f"Agent ID: {agent.id}")
# => agent_01J...

The agent_toolset_20260401 tool type gives your agent access to all built-in tools (bash, file operations, web search). You can also specify individual tools if you want finer control.

Step 3: Create an Environment

The environment is the sandbox where your agent does its work:

environment = client.beta.agents.environments.create(
    agent_id=agent.id,
)

print(f"Environment ID: {environment.id}")
# => env_01J...

Step 4: Create a Session

A session binds your agent to an environment and tracks conversation history:

session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment_id=environment.id,
)

print(f"Session ID: {session.id}")
# => session_01J...

Step 5: Send a Message and Stream the Response

This is where the magic happens. You send a message, and the agent autonomously works through the problem — executing tools, reading results, iterating — and streams events back to you:

import json

# Send a message and stream the response
with client.beta.agents.sessions.turn.stream(
    session_id=session.id,
    agent_id=agent.id,
    messages=[{
        "role": "user",
        "content": "Create a Python script that fetches the top 5 HN stories and saves them to stories.json"
    }],
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if hasattr(event.delta, "text"):
                print(event.delta.text, end="", flush=True)
        elif event.type == "tool_use":
            print(f"\n[Tool: {event.name}]")
        elif event.type == "tool_result":
            print(f"[Result: {event.content[:100]}...]")

print("\n--- Agent finished ---")

4. What Happens Under the Hood

When you send a message to a managed agent, here is what happens inside Anthropic's infrastructure:

1. Container provisioning: If the environment is cold, a Debian-based container spins up with your configured tools and any previously persisted filesystem state.
2. Agent loop starts: The model receives your message plus the conversation history and system prompt. It decides whether to respond directly or use a tool.
3. Tool execution: If the model calls a tool (e.g., bash to run a command), the harness executes it inside the container and feeds the result back to the model. This loop repeats until the model produces a final text response.
4. SSE streaming: Throughout the entire process, events are streamed back to your client in real-time — text deltas, tool calls, tool results, and status changes.
5. Idle state: After the turn completes, the container enters an idle state. It stays warm for subsequent turns but is not consuming compute. You are billed only for active compute time.

5. Built-in Tools

When you use the agent_toolset_20260401 tool type, your agent gets access to these capabilities:

6. When to Use Managed Agents vs. Messages API

7. Pricing

Managed Agents pricing has two components:

• Compute: $0.08 per hour of active container time
• Model tokens: Standard Claude pricing (varies by model tier)

Quick cost estimate: Say you run a coding agent that handles 12 sessions per day, each lasting about 10 minutes. That is 2 hours of compute per day, or $0.16/day in compute ($4.80/month). Add model costs on top — for Claude Sonnet at typical coding-agent usage, expect roughly $2-5/day in tokens. Total: around $5-8/day for a fully autonomous coding assistant.

Compare that to building your own agent infrastructure: container orchestration, tool execution sandboxing, state persistence, streaming — easily weeks of engineering time worth tens of thousands of dollars.

8. Who Is Already Using It

Anthropic highlighted several early adopters at launch:

• Notion — Using managed agents to power their AI assistant's multi-step task execution, allowing it to search, synthesize, and create content across workspaces.
• Rakuten — Deploying managed agents for automated code review and migration workflows across their engineering teams.
• Sentry — Building agent-powered debugging workflows that can reproduce issues, analyze stack traces, and suggest fixes autonomously.

9. Full Working Example

Here is a complete, end-to-end script you can save and run right now:

"""
managed_agent_demo.py
Full working example of a Claude Managed Agent.
Requires: pip install anthropic
Set ANTHROPIC_API_KEY in your environment.
"""
from anthropic import Anthropic

client = Anthropic()

# 1. Create the agent
agent = client.beta.agents.create(
    name="Research Assistant",
    model="claude-sonnet-4-6",
    system="""You are a research assistant. When asked a question:
1. Search the web for current information
2. Synthesize findings into a clear summary
3. Save the summary to a markdown file""",
    tools=[{"type": "agent_toolset_20260401"}],
)

# 2. Create an environment
env = client.beta.agents.environments.create(agent_id=agent.id)

# 3. Create a session
session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment_id=env.id,
)

# 4. Send a message and stream the response
with client.beta.agents.sessions.turn.stream(
    session_id=session.id,
    agent_id=agent.id,
    messages=[{
        "role": "user",
        "content": "Research the latest developments in quantum computing from the past week. Save a summary to quantum_update.md"
    }],
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if hasattr(event.delta, "text"):
                print(event.delta.text, end="", flush=True)

print("\nDone! The agent searched the web, synthesized findings,"
      " and saved quantum_update.md in its environment.")

Where to Go Next

The official docs are at platform.claude.com/docs/agents. They cover advanced topics like custom MCP server integration, environment snapshots, multi-agent orchestration, and token budget controls.

If you are building agents that need well-structured system prompts and configurations, our SOUL.md Generator creates agent configuration files tuned for Claude's instruction-following patterns. And if you want to go deeper on Claude Code itself — hooks, CLAUDE.md templates, subagent workflows — the Claude Code Mastery Kit covers all of it.