Claude Managed Agents: Complete Developer Guide (April 2026)

The Architecture: Brain, Hands, and Session

Anthropic describes the Managed Agents architecture using three components. Understanding the separation helps predict where the platform adds value and where your application logic lives.

The Brain

The brain is Claude plus the agent harness — the model you select (Sonnet 4.6, Opus 4.6, or Haiku 4.5), the system prompt you write, the tool definitions you declare, and the Plan → Act → Observe → Decide loop that drives agent execution. This entire layer is yours to define and own. The platform executes it; you author it.

The Hands

The hands are the execution environments: sandboxed Linux containers that handle code execution, file manipulation, and external tool calls. Each session launches in a fresh, disposable container. The container has access only to the tools you provisioned for the agent and the credentials you scoped to the session. When the session ends, the container is destroyed, leaving no state that could leak between sessions or users.

Built-in tool types available in the platform include bash execution (bash_20260401), file read/write (read_20260401, write_20260401), and web fetch. You can enable the full toolset at once with agent_toolset_20260401, or granularly provision individual tools depending on the access your agent actually requires. You can also define custom tools backed by your own APIs, with Anthropic’s infrastructure handling invocation and returning results into the agent context.

The Session

The session is a durable event log that records every action the agent takes: every tool call, every model response, every tool result. Crucially, this log persists independently of the client network connection. If a connection drops mid-task, the session resumes from the last recorded state when the client reconnects — rather than restarting the entire task from the beginning.

Sessions are identified by a unique session ID returned when you create them via the API. You can stream live events, retrieve the complete log for a completed session, or resume an interrupted session. The event log is also the foundation for the platform’s built-in observability: every tool call and its result are captured with timestamps and duration, giving you production-quality traces without instrumenting your application code.

Pricing: $0.08 Per Session-Hour Explained

Claude Managed Agents charges two dimensions: standard Claude API token rates for all model inference, plus $0.08 per session-hour for active agent runtime. Understanding what “active” means is essential for accurate cost modeling.

Runtime is measured to the millisecond and accrues only while the session’s status is running. The session clock pauses when:

• The session is waiting for a human-in-the-loop confirmation step
• An asynchronous tool call (web scrape, file download) is executing and the agent is waiting
• The session has completed a sub-task and is idle awaiting the next user input
• The session has been explicitly paused via the API

This billing model means a research agent that actively runs for four hours but waits at three human-review steps for another eight hours accumulates four session-hours of runtime, not twelve. For workflows with meaningful human oversight checkpoints, the effective cost per completed task is significantly lower than the nominal session-hour rate suggests.

For a typical coding agent task — scaffolding a new feature, writing tests, opening a pull request — active session time is usually 10–30 minutes. At $0.08 per session-hour, that is roughly $0.013–$0.04 per task in platform fees before token costs. For most production agentic workloads, the platform fee is a small fraction of total inference cost. Use the AI prompt cost calculator to model both token costs at your target model rate and the $0.08/session-hour platform overhead for your estimated active session time per task.

Getting Started: The API in Three Steps

All Managed Agents API requests require the managed-agents-2026-04-01 beta header. The core workflow is: create an agent, start a session, stream events.

Step 1: Create an Agent Definition

curl 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": "code-reviewer",
    "model": "claude-sonnet-4-6",
    "system": "You are a senior software engineer reviewing pull requests. Analyze diffs thoroughly, identify bugs and security issues, and write constructive reviews.",
    "tools": [
      { "type": "agent_toolset_20260401" }
    ]
  }'

The response returns an agent_id (e.g., agt_01XYZ...) that you reference when creating sessions. Agent definitions are versioned — you can update an agent’s system prompt or tools without interrupting any currently running sessions.

Step 2: Create a Session

curl 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_id": "agt_01XYZ...",
    "environment": {
      "secrets": [
        { "name": "GITHUB_TOKEN", "value": "ghp_..." }
      ]
    }
  }'

Secrets passed in the environment object are injected into the session container as environment variables and are never written into the agent’s context window. The agent accesses them through its sandbox tools (bash commands can read $GITHUB_TOKEN) without the secret appearing as a string in any conversation turn. This is the credential isolation model that most teams get wrong when building their own infrastructure.

Step 3: Stream Agent Events

curl 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" \
  -d '{ "message": "Review the diff at https://github.com/org/repo/pull/247" }'

Events stream as server-sent events (SSE). The typed event stream includes agent.thinking, tool.call, tool.result, agent.response, and session.complete. You can subscribe to specific event types to build real-time progress UIs, trigger downstream webhooks, or log structured traces to your observability stack.

Session Persistence: The Feature That Matters Most in Practice

Session persistence is the least flashy and most practically consequential feature on the platform. Multi-step agentic tasks often run for 15–90 minutes. Network interruptions are inevitable at that timescale. Before persistent sessions, a dropped connection meant restarting the entire task from scratch — losing all intermediate progress, tool results, and accumulated context across dozens of agent turns.

With Managed Agents, the session event log exists independently of any client connection. When a connection drops and reconnects, the client calls the events endpoint with the ID of the last event it received. Streaming resumes from that point. The agent never sees the interruption because it happened at the transport layer, not the session layer.

For long-running research agents, overnight data processing pipelines, or any agentic workflow where a restart is expensive, this reliability changes what is feasible to build. A background agent that runs autonomously for hours without any active user connection becomes a straightforward product decision rather than a custom infrastructure project requiring significant engineering investment.

Who Is Already Using It

Anthropic announced four production partners at the April 8 launch, covering a range of agentic use cases:

Notion is using Claude Managed Agents to power multi-step writing and research features. Their agents read existing documents, search the web for supporting information, and generate structured content. Session persistence is critical for Notion’s use case because users expect long-running background tasks to complete without monitoring them.

Rakuten is running shopping research agents that autonomously find products, compare prices across sellers, evaluate reviews, and generate purchase recommendations. The sandboxed web fetch tool allows agents to retrieve product data from external retailers without any risk of credential exposure or cross-session contamination.

Sentry is using agents for parts of its error triage workflow: agents that read error reports, clone the associated repository, examine code context, identify likely root causes, and draft initial fix proposals. The code execution sandbox handles repository operations in isolated containers, ensuring triage agents cannot accidentally modify production state.

Asana is deploying agents for project management automation — creating task breakdowns from high-level goals, assigning work based on team workload, and generating status updates. The human-in-the-loop confirmation flow (where billing pauses while waiting for approval) fits naturally into Asana’s approvals-based workflows, keeping the cost model aligned with actual automated activity.

Managed Agents vs. Building Your Own Infrastructure

The honest comparison depends on how much of this infrastructure problem you have already solved.

If you have already built containerization, session persistence, credential management, and error recovery into your agent stack, Managed Agents is primarily a billing simplification and an operational cost reduction. You could migrate, but you are not gaining capabilities you do not already have. Weigh the $0.08/session-hour platform fee against your actual operational costs (container compute, database for session state, secret management service) for equivalent infrastructure at your session volume.

If you are starting fresh, Managed Agents is clearly the faster path. According to our analysis, at $200/hour senior developer rates, six weeks of infrastructure work costs roughly $48,000 in engineering time before you have shipped a single user-facing agent feature. The platform fee starts at $0 before you have any sessions running. For teams without an existing agent infrastructure investment, the build-vs-buy calculation is not close.

Amazon Bedrock AgentCore (launched earlier in 2026) offers comparable sandboxing and state management on the AWS stack. If your existing infrastructure is AWS-native, see our Bedrock AgentCore production guide for a direct comparison. Claude Managed Agents is the better choice if you are Claude-native and want tight integration with Anthropic’s evolving model features — including the Advisor Strategy.

Combining Managed Agents with the Advisor Strategy

Anthropic released both features within 24 hours of each other for a reason. They solve adjacent problems and are designed to compose.

Claude Managed Agents solves the infrastructure problem: how do you run agents reliably in production without building your own container orchestration and session management? The Advisor Strategy (released April 9, 2026) solves the cost-quality problem: how do you get Opus-level reasoning on the hard parts of a task without paying Opus rates for every routine step?

In combination: your agent runs on the Managed Agents platform, handling all operational concerns transparently. Inside that agent’s loop, the executor model (Sonnet 4.6) calls the advisor_20260301 tool when it encounters genuinely hard decisions. Opus 4.6 advises silently on those specific steps. The Managed Agents platform sees the advisor call as just another tool call — it does not need any special handling. The result is production-grade operational reliability combined with optimized intelligence economics. For the full Advisor Strategy implementation guide, see our complete walkthrough.

What Is Still in Research Preview

Two capabilities were announced alongside Managed Agents but are not yet in general availability:

Multi-agent coordination — the ability to spawn sub-agents from within a running session, with the parent session maintaining orchestration state across all child agents. This is the pattern behind agent networks where a planning agent delegates subtasks to specialist agents running in parallel. It requires a separate access request and is expected to reach general availability in Q2 2026.

Self-evaluation — a structured mechanism for agents to assess the quality of their own output before finalizing it, generating a confidence score and reasoning trace alongside the primary answer. Useful for applications where output reliability is critical and the cost of human review on every task is prohibitive. Also in research preview with the same expected GA timeline.

Developer Recommendation

For developers starting a new agent project: use Managed Agents from day one rather than custom infrastructure. The time savings are real, the pricing is predictable, and session persistence alone eliminates the most common production failure mode in agentic applications. You can migrate off the platform later if you outgrow its constraints — but you will not hit those constraints before you know whether the agent is worth the infrastructure investment.

For teams currently running agents on custom infrastructure: audit your actual operational costs — container compute, session state storage, secret management, on-call engineering time for agent incidents — against $0.08/session-hour for equivalent session volume. For most teams running fewer than a few thousand sessions per day, the platform cost is lower than self-managed infrastructure once incident response and maintenance time are included. Migration is worth evaluating seriously if session persistence or credential exposure have caused production incidents in your current setup.

For teams building the agent-plus-advisor combination: this is the complete Anthropic architecture for production intelligent agents as of April 2026 — Managed Agents for operational reliability, Advisor Strategy for intelligence economics. Both are available in public beta now. Add the managed-agents-2026-04-01 beta header to your API requests to start your first session. For a hands-on walkthrough of the complete agent loop from scratch, see our zero-to-production agent tutorial.