Chapter 1: What Is a Managed Agent?
By the end of this chapter, you will understand exactly how Claude Managed Agents differs from a chatbot and from the raw Messages API — and why that difference matters for the kind of work you want to get done.
The Big Idea
When most people use AI, they're having a conversation. They type something, the AI responds, and that's the transaction. The AI has no hands. It can't open a file, run a script, search the web, or send an email. It can only speak.
An agent is different. An agent can act.
Claude Managed Agents gives Claude a fully equipped workspace — files, a terminal, web access, code execution — and lets it work through a task from start to finish without you babysitting every step. You hand it a goal. It figures out the steps, uses its tools, checks its work, and delivers the result.
The "managed" part is equally important. Anthropic runs the infrastructure. You don't need to provision servers, set up containers, write your own retry logic, or build the loop that keeps the agent running when something fails. That entire layer is handled for you.
The official positioning from the Anthropic overview docs captures it cleanly:
| Messages API | Claude Managed Agents | |
|---|---|---|
| What it is | Direct model prompting access | Pre-built, configurable agent harness that runs in managed infrastructure |
| Best for | Custom agent loops and fine-grained control | Long-running tasks and asynchronous work |
This book is about the right column.
The Analogy
Think of the difference between a consultant on a call and a contractor who has the keys to your office.
The consultant on a call is sharp and helpful. Ask them anything, and they'll give you a great answer. But they can't do the work while you're talking. They can't open your spreadsheet, fix the formula, rerun the analysis, and email the updated file to your client. Every action still requires you.
The contractor with the keys is different. You give them a clear brief on Monday morning, they let themselves in, use whatever tools are available in the space, do the work, and leave the finished product on your desk by Friday. You can check in anytime, but you don't have to.
Claude Managed Agents is the contractor. You define the brief (the system prompt and task), set the rules for what they can and can't do unsupervised (permission policies), and let them work. The managed infrastructure is the office: pre-stocked with tools, secure, and ready to go.
How It Actually Works
Claude Managed Agents launched in public beta on April 8, 2026. All API accounts have access enabled by default — no waitlist, no special application needed.
The official description is precise: "Claude Managed Agents provides the harness and infrastructure for running Claude as an autonomous agent. Instead of building your own agent loop, tool execution, and runtime, you get a fully managed environment where Claude can read files, run commands, browse the web, and execute code securely. The harness supports built in prompt caching, compaction, and other performance optimizations for high quality, efficient agent outputs." (Overview)
Let's unpack what that means in practice.
The Agent Loop
When you run a standard language model, the interaction is stateless. You send a prompt. The model generates tokens. Done. If you want the model to "think in steps," you have to build that yourself — sending the output back in as input, managing the history, handling tool calls, writing retry logic.
Claude Managed Agents handles all of this. The "harness" is the loop: it calls Claude, routes Claude's tool requests to the right execution environment, gets the results back, and feeds them into the next step. It keeps running until the task is complete or you tell it to stop.
Why "Managed" Matters
The word "managed" signals that Anthropic runs the infrastructure. In practice, this means:
- You don't provision containers. Anthropic runs a secure cloud environment for each session. Each session gets its own isolated container with Ubuntu 22.04, up to 8 GB of memory, 10 GB of disk, and a full set of pre-installed tools.
- You don't write retry logic. If a transient error occurs, the session status moves to
reschedulingand the harness automatically retries. If the harness itself fails, a new one reboots from the durable session log. - You don't manage state. The entire conversation and tool-use history is stored as an append-only event log, accessible to you at any time via the API.
When to Use Managed Agents
According to the overview documentation, Managed Agents is the right choice for workloads that need:
- Long-running execution — tasks that run for minutes or hours with multiple tool calls
- Cloud infrastructure — secure containers with pre-installed packages and network access
- Minimal infrastructure — no need to build your own agent loop, sandbox, or tool execution layer
- Stateful sessions — persistent file systems and conversation history across multiple interactions
If your task takes less than a few seconds, requires extreme fine-grained control over every model call, or is essentially just a single prompt-and-response, the Messages API is still the right fit. For everything that looks more like delegated work than a conversation, Managed Agents is purpose-built.
The Three Things You Always Create
Every Managed Agents workflow involves three core objects, in order:
- An Agent — the reusable configuration (model, persona, tools)
- An Environment — the container configuration (what packages are installed, what network access is allowed)
- A Session — the actual running instance that combines an agent with an environment and does the work
You create the agent and environment once. You create sessions repeatedly — one per task, or one per user, or one per workflow run. This chapter introduced what the agent is. The next three chapters build out the complete mental model before you write any code.
Try It Yourself
You don't need to write code yet — this exercise is about getting your bearings.
Get your API key. If you don't have one, go to console.anthropic.com and create an account. All API accounts have Managed Agents access enabled by default.
Install the
antCLI. This is Anthropic's command-line tool for Managed Agents. Check whether you have it:ant --version # If this errors, install it via npm: npm install -g @anthropic-ai/antPlain English: this checks whether the
anttool is installed. If not, the comment shows you how to install it.Set your API key as an environment variable:
export ANTHROPIC_API_KEY="your-api-key-here"Plain English: this stores your key so the CLI can use it without you typing it every time.
Read the overview docs. Open platform.claude.com/docs/en/managed-agents/overview. Find the comparison table between the Messages API and Managed Agents. Take note of which use cases land in each column.
Write down one task you currently do manually that takes 30 minutes to 4 hours, involves files or the web, and has a clear definition of "done." That is your first agent candidate. Keep it handy — you'll build toward it through the rest of the book.
Common Pitfalls
Using Managed Agents for single-turn tasks. If your task is "summarize this paragraph," use the Messages API directly. Managed Agents adds setup overhead (agent, environment, session) that only pays off for multi-step, multi-tool work. A good rule of thumb: if the task has more than three distinct steps or needs to use a tool, consider Managed Agents.
Confusing "agent" with "session." The agent is a reusable configuration — like a job description. The session is the actual worker doing a specific job. You update the agent when you want to change its behavior for all future sessions; you create a new session for each new piece of work.
Expecting it to work like a chat interface. Managed Agents is asynchronous. You send a task, and the agent works through it. You can watch progress through the event stream, but you're not having a back-and-forth conversation in real time. Think "delegating to a contractor," not "chatting with an assistant."
Not defining the task clearly enough. Claude is capable, but it's not a mind reader. The quality of your result is proportional to the clarity of your brief. Vague tasks produce vague work. Specific tasks produce specific results. Chapter 6 covers system prompt design in detail.
Toolkit
Template: Agent Use Case Evaluator — A one-page worksheet to determine whether a task is a good fit for Managed Agents or is better handled with a direct API call. Includes the key questions: How many steps? Does it need tools? Is the definition of "done" clear?
Checklist: Managed Agents Readiness Check — Five yes/no questions to confirm your account is set up and ready to create your first agent.
Chapter Recap
- Claude Managed Agents is a managed infrastructure layer that gives Claude tools to act, not just speak. You get a secure container, a persistent event log, and an autonomous execution loop — without building any of it yourself.
- The key distinction from the Messages API: Managed Agents is for long-running, multi-step, stateful work. The Messages API is for fine-grained, single-turn, or lightweight tasks.
- Every workflow involves three objects created in order: an Agent (the configuration), an Environment (the container), and a Session (the running instance). Agent and Environment are reusable. Sessions are disposable — create one per task.