Claude Managed Agents: what they are and how to run one

What are Claude Managed Agents?

Claude Managed Agents lets you give Claude a task and get back finished work, without building the loop that runs it. Anthropic hosts the sandbox, runs the tools and keeps the session. You send messages and read events.

It is a pre-built, configurable agent harness that runs on Anthropic’s infrastructure, built for long-running and asynchronous work. It is in beta on the Claude Platform. Every request carries the managed-agents-2026-04-01 beta header, and the SDKs set it for you. The harness includes prompt caching and compaction, so long sessions stay efficient without extra code.

This guide covers the four concepts, working calls to create and run an agent, tools and permissions, cost, limits, and how to tell whether a session did what the person asked.

The choice is simple. Use the Messages API when you need to control every step of the loop. Use Managed Agents when the job is a task that runs for minutes or hours and you would rather not build the runtime.

The four concepts: agent, environment, session, events

Everything in the product is one of four things. Learn these and the API reads like a sentence: this agent, in that environment, working one session, talking through events.

A run follows five steps.

• Create an agent. Define it once and reference it by ID in every session.
• Create an environment. Choose the sandbox and its network rules.
• Start a session. Point it at the agent and the environment.
• Send events and stream the reply. Claude runs tools on its own and streams results back as server-sent events. The event history is stored server-side.
• Steer or interrupt. Send more events to guide the agent mid-run, or stop it and change direction.

Agents are versioned. A new agent starts at version 1, and the number goes up each time an update changes the configuration. Pass the current version when you update and a stale write returns a 409 instead of silently replacing someone else’s change. You can also override the model, system prompt, tools, MCP servers or skills for a single session without touching the agent. Archiving an agent makes it read-only: new sessions cannot use it, and running ones carry on.

Create the agent, environment and session

The examples use the design-tool assistant from the rest of this site: an agent that resizes one banner for every social channel a person names. Set ANTHROPIC_API_KEY first. The calls below use plain curl, and the quickstart also covers the ant CLI and seven SDKs.

Create the agent

curl -fsSL 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": "Banner resizer",
    "model": "claude-opus-5-5",
    "system": "You resize design banners for the channels a person names. Check every file before you send it.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }'

The response echoes your configuration and adds an id and a version. Save the ID. Four fields do the work:

• name. Required. A human-readable label.
• model. Required. A model ID string, or an object when you also want to set speed, effort or inference_geo. Claude 4.5 and later models are supported.
• system. The prompt that sets behaviour and persona. Keep it separate from user messages, which describe the work.
• tools. The pre-built toolset, MCP tools and custom tools. agent_toolset_20260401 switches on all the built-in tools at once.

Create the environment

curl -fsSL 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": "banner-env",
    "config": {
      "type": "cloud",
      "networking": {"type": "limited", "allow_package_managers": true}
    }
  }'

With limited networking and package managers allowed, code in the sandbox can install libraries from public registries. One detail catches people out: web search and web fetch run outside the sandbox, but the allowed_hosts list still applies to them. An environment that lists no hosts returns no pages and no search results. List the hosts your agent needs.

Start the session

curl -fsSL 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": "'"$ENVIRONMENT_ID"'",
    "title": "Resize the spring banner"
  }'

Nothing runs yet. The session is idle until it receives its first event.

Send a task and read the stream

Open the stream first, then send the message. A stream delivers only events emitted after it opens, so the other order can miss the start of the reply.

from anthropic import Anthropic

client = Anthropic()

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": "Resize this banner for every channel we post on."}],
        }],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")
            case "session.status_idle":
                print("\nAgent finished.")
                break

Event names follow a {domain}.{action} pattern. The agent runs its tools inside the sandbox and the stream reports each step. When it has nothing left to do, it emits session.status_idle. Try it below. The log is the one a real session would produce for turns 5 to 8 of the banner conversation.

These are the events you will handle most.

Two stop_reason values matter first. end_turn means the agent finished its turn, or you interrupted it. requires_action means it is waiting on you, and stop_reason.event_ids lists the calls to answer. Webhooks are separate from the stream, and a few names differ: webhooks use session.status_idled, not session.status_idle.

The full event history stays on the server, so you can reconnect and fetch what you missed. Events are also available as previews: opt in to event deltas on a stream to render replies as they are written. Deltas are never stored.

Choose what the agent can do

The toolset in the example switches on eight built-in tools. All are enabled by default.

Give an agent less than the full set when the job is narrow. Start with everything off, then switch on only what you need:

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash",  "enabled": true },
    { "name": "read",  "enabled": true },
    { "name": "write", "enabled": true }
  ]
}

Beyond the built-ins, an agent can use three more things.

• Custom tools. You define the name, description and input schema. Claude emits a request, your code runs it, and you return the result as user.custom_tool_result.
• MCP servers. Remote servers with an HTTP endpoint, or private ones through MCP tunnels, which are in a limited research preview.
• Skills. Reusable domain knowledge that loads progressively, so it does not fill the context up front.

Two newer features change how “done” is decided. With outcomes, you send user.define_outcome with a markdown rubric. A separate grader, in its own context window, scores the work against each criterion and hands feedback back until the result is satisfied, or max_iterations runs out (default 3, maximum 20). With multiagent configuration, an agent can hand work to subagents or consult an advisor model. Anthropic’s launch post called both research previews, so check current access before you plan around them.

Steer, interrupt and approve

A session is a conversation you can step into at any point. Five events cover it.

• Steer. Send another user.message while the agent works to redirect it.
• Interrupt. Send user.interrupt to stop the agent mid-run.
• Resume. An idle session accepts a new user.message and continues with its files and history intact.
• Add context. system.message appends system-level context for the turn and every turn after it, on models that accept it.
• Approve. user.tool_confirmation answers a tool call that a permission policy held back.

Permission policies decide which tool calls need that approval. They apply to the built-in toolset and MCP tools. Custom tools run in your code, so you control them directly.

Set a policy per tool. To hold back only bash:

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "bash", "permission_policy": { "type": "always_ask" } }
  ]
}

When a call is held, the session goes idle with stop_reason.type set to requires_action. Answer each blocking event with user.tool_confirmation, passing its ID as tool_use_id and result as "allow" or "deny". A denial can carry a deny_message, and the agent receives it as the tool result. The session waits indefinitely, so a held call that nobody answers is a stuck session.

What do Claude Managed Agents cost?

Two things are billed. Tokens are charged at the standard Claude Platform rates for the model you pick. Active runtime is charged per session-hour. At launch, Anthropic listed that runtime rate as $0.08 per session-hour.

Rates change, so read the current figure on Anthropic’s pricing page before you budget. The arithmetic stays the same. Take a session that is actively running for 12 minutes:

• One session. 12 minutes is 0.2 hours. 0.2 × $0.08 = $0.016 of runtime.
• 100 sessions. 100 × 0.2 = 20 hours. 20 × $0.08 = $1.60 of runtime.
• Tokens on top. Each session also uses tokens, and span.model_request_end reports the counts per model call.

Runtime is rarely the large number. Token use grows with the length of the task, so the sessions that run longest cost the most. Watch the session.usage event, which carries cumulative usage and cost, and set a budget if a task could run away.

When Managed Agents fits

Anthropic’s documentation names six workloads. Each is a reason not to write the runtime yourself.

• Long-running execution. Tasks that run for minutes or hours with many tool calls.
• Cloud infrastructure. Secure sandboxes with pre-installed packages and network access.
• Self-hosted execution. Sandboxes on your own infrastructure for compliance or data residency.
• Minimal infrastructure. No agent loop, sandbox or tool runner to build.
• Stateful sessions. A filesystem and conversation history that persist across interactions.
• Scheduled execution. Recurring runs on a cron schedule, with credentials kept in vaults.

The launch post lists early users including Notion, Rakuten, Asana, Sentry and Atlassian, with work ranging from delegated coding tasks to agents that sit in Slack and Jira. Anthropic also reported, from its own testing on structured file generation, gains of up to 10 points in task success over a standard prompting loop. Treat that as the vendor’s result on one task type, and test your own.

What the event stream cannot tell you

Every event above reports what the agent did. None reports whether the person got what they asked for. The Claude Console adds session tracing, so you can inspect tool calls, decisions and failures. That is the right tool for the run.

Look again at the session above. It ended with end_turn and raised no session.error. The agent sent 3 of the 9 sizes. At turn 9 the person wrote “Where are the rest? Can you try that again?” That sentence reaches your app as a user.message. Nothing in the log marks it as a failed task.

Now scale it. Picture 2,400 sessions like this one. The stream shows 2,400 sessions that went idle. The task shows 1,536 that finished, 64%, and 528 that stopped on resize it. A rubric helps here, because it grades the artifact against criteria you wrote in advance. People also ask for things you wrote no criterion for. Reading those requests is a different job, and it needs four things:

• Task. What the person came to do, and whether it finished.
• Intent. The smaller goals inside the task: find the formats, resize it, export the files.
• Signal. What happened at each turn: blank sizes at turn 7, dissatisfaction at turn 9.
• Cohort. Which plans, regions or returning users do worse on the same task.

Your app already sends every user.message and receives every agent.message, so the conversation is yours to keep. Abracadabra reads topic, task, intent and signal from the conversations you connect, then lets you compare cohorts and replay the turns behind a number. The features page walks through that path, and you can try it free with up to 1,000 conversations a month: see pricing. For the method, read how to measure AI agent performance.

When Managed Agents is the wrong tool

It trades control for convenience. Some jobs want the control back.

• You need to own the loop. If you want to decide every step, call the Messages API directly. That is its stated purpose.
• The job is one quick call. A single prompt and reply does not need a sandbox, a session or an event stream.
• You need zero data retention or a HIPAA BAA. Sessions are stateful and store history, sandbox state and outputs server-side. Managed Agents is not currently eligible for either. You can delete sessions, and files you uploaded, at any time.
• You need stable behaviour. The product is in beta, and Anthropic may refine behaviours between releases.
• You create sessions in bulk. Create endpoints allow 300 requests per minute per organisation, and read endpoints allow 1,200. Spend limits and usage-tier limits also apply.
• You assume a finished session is a finished task. end_turn says the agent stopped. It does not say the person was served.

Claude Managed Agents FAQ

What are Claude Managed Agents?

Claude Managed Agents is a pre-built agent harness that runs on Anthropic’s infrastructure. You define an agent and an environment, start a session, and exchange events while Claude runs tools in a sandbox.

What is the difference between Claude Managed Agents and the Messages API?

The Messages API gives direct model access, and you build the agent loop. Managed Agents supplies the loop, the sandbox and the session storage, and it is built for long-running, asynchronous work.

How much do Claude Managed Agents cost?

You pay standard token rates for the model plus a per-hour charge for active session runtime. Anthropic listed $0.08 per session-hour at launch, so check the current pricing page.

Can Claude Managed Agents run on my own infrastructure?

Yes. An environment can be an Anthropic-managed cloud sandbox or a self-hosted sandbox on infrastructure you control, which suits compliance and data-residency needs.

Is Claude Managed Agents still in beta?

Yes. Anthropic documents it as beta and requires the managed-agents-2026-04-01 header on every request. Access is enabled by default for API accounts, and MCP tunnels and dreaming are in a more limited research preview.

How do I know whether a managed agent finished the person’s task?

A finished session only means the agent stopped. Check the result against the request, and read the conversation for corrections and repeats. Abracadabra classifies each conversation by task and intent so you can see where work stopped.

Related guides

• How to measure AI agent performance in production: Requests, task outcomes, friction and policy signals, with the conversation behind each count.
• What is AI agent observability?: How traces, evaluations and conversation analytics fit together.
• What is AI agent analytics?: Reading live conversations to find what people came to do and where the agent lost them.
• Conversation analytics for AI agents: Why sentiment scores miss conversational failure, and how to find the deciding turn.

Sources: Anthropic’s Managed Agents documentation and launch post.