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

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:

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

• 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):

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.