Claude Managed Agents

Overview

Anthropic released Claude Managed Agents in beta. It sits alongside the Messages API and provides a pre-built agent harness plus managed infrastructure.

Instead of writing your own agent loop, tool-execution layer, and sandbox, you get an environment where Claude autonomously reads/writes files, runs shell commands, searches the web, and executes code.

How it differs from Messages API

	Messages API	Managed Agents
Shape	Direct model prompting	Managed agent harness
Best for	Custom agent loops, fine-grained control	Long-running, asynchronous work
Infrastructure	You build it	Anthropic runs it

Core concepts (4)

• Agent — configuration bundle: model, system prompt, tools, MCP servers, skills
• Environment — cloud container template with packages, network access, and mounted files
• Session — an instance that runs on top of an agent + environment to perform a specific task
• Events — messages exchanged between your app and the agent (user input, tool results, status)

How it works

1. Create an Agent — define model, system prompt, and tools; reuse by ID.
2. Create an Environment — container with Python, Node.js, or any packages you need.
3. Start a Session — reference an agent + environment to run.
4. Send/receive events — send user messages; Claude autonomously calls tools and streams results over SSE.
5. Steer mid-run — emit events during execution to adjust direction or halt.

Built-in tools

• Bash — shell inside the container
• File operations — read, write, edit, glob, grep
• Web search / fetch — search and fetch URL content
• MCP servers — connect external tool providers

When it fits

• Long-running work — multi-step tool use spanning minutes to hours
• Needs cloud infra — secure container with your package set
• Minimal ops — you don’t want to own the agent loop, sandbox, and tool layer
• Stateful sessions — filesystem and conversation history persisted across interactions

Getting started

Managed Agents is enabled by default on every Anthropic API account, so you can start using it immediately — no access request required (only research-preview features like Dreaming need a separate sign-up).

Prerequisites

• An Anthropic Console account and an API key
• An SDK (Python, TypeScript, Java, Go, C#, Ruby, PHP) or any HTTP client for direct calls
• The anthropic-beta: managed-agents-2026-04-01 header on every request — SDKs set it automatically

Install the SDK and set your key

# Python
pip install anthropic

# TypeScript
npm install @anthropic-ai/sdk

# Common: set the API key
export ANTHROPIC_API_KEY="..."

The four-call flow

1. Create an Agent — define the model, system prompt, and toolset (agent_toolset_20260401); reuse the returned agent.id across sessions.
2. Create an Environment — configure the container (networking, pre-installed packages, mounted files); reuse the returned environment.id.
3. Create a Session — reference an agent + environment to spin up a running instance.
4. Send and stream events — send a user.message event; Claude autonomously calls tools and streams results back over SSE. You can also send additional events mid-run to steer or interrupt the agent.

Minimal Python example:

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding assistant.",
    tools=[{"type": "agent_toolset_20260401"}],
)

environment = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Quickstart",
)

The full event-streaming example — across all seven SDKs, the CLI, and curl — is in the official Quickstart.

Interactive onboarding

Run /claude-api managed-agents-onboard in the latest Claude Code for a guided, interactive walkthrough (per the official docs).

Rate limits

Per organization, with tier-based API limits applied on top:

Endpoint type	Limit
Create (agents, sessions, environments, etc.)	300 requests/min
Read & stream (retrieve, list, stream, etc.)	600 requests/min

Pricing

Two components: token cost + session runtime.

Tokens

• Same per-model token rates as Messages API
• Prompt caching discounts apply
• Web search billed at $10 per 1,000 searches

Session runtime

Item	Rate	Basis
Session runtime	$0.08 / hour	Time in running state

• Metered in milliseconds.
• Billed only while in running; idle, rescheduling, and terminated states are not billed.
• Replaces Code Execution container-time billing (no double-billing).

Example cost

A 1-hour coding session with Claude Opus 4.6 (50K input tokens, 15K output tokens):

Item	Calculation	Cost
Input tokens	50,000 × $5/MTok	$0.25
Output tokens	15,000 × $25/MTok	$0.375
Session runtime	1 hr × $0.08	$0.08
Total		$0.705

What’s different from Messages API

The following discounts/options don’t apply to Managed Agents:

• Batch API discount (sessions are stateful/interactive)
• Fast mode premium (runtime manages inference pace)
• Data residency options
• Third-party platforms (AWS Bedrock, Vertex AI) — Claude API direct only

Notes

• Currently in beta — all endpoints require the managed-agents-2026-04-01 beta header.
• SDK sets the beta header automatically.
• Enabled by default on every API account.
• outcomes, multiagent, and memory features are in separate research-preview opt-ins.