PART 01

What Are Managed Agents

A configurable agent harness on managed infrastructure. It can reason and use enabled tools, but authority, safety, and business correctness remain your responsibility.

Beta · reviewed 31 Aug 2026 · verify before use

Source: Anthropic's Managed Agents overview. All Managed Agents endpoints require managed-agents-2026-04-01; memory-store endpoints currently use a separate header. Beta behavior may change.

4 Core Concepts

The API is organized around four resources. Treat Agent and Environment definitions as governed configuration, and bind every Session to an explicit version and trust boundary.

🧠
Agent
A versioned configuration for the model, system prompt, tools, MCP servers, and skills. Changes apply to later sessions, so record the tested version.
📦
Environment
Where sessions run: an Anthropic-managed cloud sandbox or your self-hosted sandbox. It defines packages, networking, and the execution boundary.
▶
Session
A running agent instance tied to an environment. It carries conversation history, files, outputs, usage, and lifecycle state for a task.
⚙
Events
Persisted user turns, model messages, tool calls, results, status, and usage. Stream them with SSE and retain only what policy permits.

How It Flows

Your application selects a tested Agent version and Environment, starts a Session, sends an event, and observes the event stream. It must also authorize tools, handle approvals, interrupt unsafe work, and validate outputs.

YOU AGENT ENVIRONMENT SESSION EVENTS STREAMED BACK TO YOU

What “Managed” Does Not Mean

The service reduces harness and runtime work. It does not certify a workflow, authorize business actions, or remove application responsibilities.

Authorization
Grant the smallest data, filesystem, network, and tool scope. The built-in agent toolset can default to always_allow; safe behavior is not automatic.
Data Boundaries
Separate tenants, sessions, credentials, storage, and logs. Do not give one agent or environment broad access across unrelated customers.
Verification
Evaluate representative, adversarial, prompt-injection, and regression cases. Model output is a proposal until deterministic checks or a qualified human accepts it.
Operations
Set spend, time, turn, and rate caps; preserve useful logs without secrets; and design stop, kill, replay, and rollback paths before enabling writes.

Messages API vs Managed Agents

If you've used Claude's Messages API before, here's what changes.

FeatureMessages APIManaged Agents
Agent loopYou design and host itManaged harness
ExecutionYour infrastructure and isolationCloud or self-hosted sandbox
Files and commandsYou implement any toolsAvailable only when configured
Tool authorizationYour application enforces itYour policies/application enforce it
StateYou choose and persist itSession event history and filesystem
ObservabilityYou instrument itEvent stream plus your logs and alerts
Long-running workPossible with your orchestrationDesigned for asynchronous sessions
Production safetyRequires your threat model, evaluation, access controls, approvals, monitoring, and incident plan

When to Use Managed Agents

Not every task needs an agent. Here's when they make sense.

⏰
Long-running or asynchronous work with multiple tool calls, where a managed harness is useful and the task can be stopped safely.
☁
Cloud sandboxes when the data class permits managed execution; self-hosted environments when compliance or residency requires your infrastructure.
⚡
A bounded pilot that starts with synthetic fixtures and read-only tools before any customer data or consequential action.
📋
Stateful sessions where retention, deletion, privacy, and legal review are explicitly acceptable for the intended data.