AI Engineer World's Fair 2026

Decoupling the Brain from the Hands: Claude Managed Agents (Part 1 of 4) — Anthropic

Read the talk

Decoupling the Brain from the Hands: Claude Managed Agents (Part 1 of 4)

Anthropic’s first Managed Agents architecture put the session history, harness and sandbox in one container. Separating them changed failure recovery, credential handling, context management and the path to a first response.

From a talk by Priyanka Phatak and Gabe Cemaj

At a glance

Ideas worth remembering

  • Harness workarounds depend on model behavior. Separating interfaces lets the harness change when those assumptions become stale.

  • The session log preserves continuity while the harness and sandbox remain replaceable. Sandbox failure returns a decision to Claude; harness failure is recovered by reading the log.

  • Injecting tokens at an outbound proxy keeps credentials out of the sandbox and away from model-visible requests to print or save them.

  • Preserved events support different context strategies, while on-demand sandbox provisioning lets inference begin sooner. Anthropic reports about 90% lower time to first token.

  • An environment and agent definition create an idle session; events start its work, carry custom tool exchanges, report state and allow interruption.

A harness carries assumptions about the model

A model approaching its context limit can change how it works. In Priyanka Phatak’s opening example, an earlier Claude model developed what Anthropic called “context anxiety”: it tried to wrap up the task quickly as the available context ran out. A harness could compensate with a context reset. A subsequent model no longer needed that workaround. The engineering problem was keeping the surrounding software useful as the model’s limitations changed.

Phatak leads the Claude Managed Agents engineering team at Anthropic. This first workshop installment moves from the architecture’s evolution to the API concepts behind a simple joke-telling agent; Gabe Cemaj introduces himself as an engineer on the same team, with a more involved financial-agent exercise planned for later in the workshop.

The starting definition is deliberately small: an agent is a model in a loop with tools. The model chooses an action, calls a tool and continues until the task is done. The harness implements the surrounding machinery: running that loop, making tool calls and managing context. Those responsibilities embed judgments about what the model can handle and where software needs to compensate. A workaround that helps one model can become unnecessary with the next.

The agent also needs somewhere to act. A sandbox gives it a computer on which it can execute generated code, edit files and install dependencies. Claude Code supplies a familiar example of a harness working against local files. In production, generated code may be buggy or otherwise untrusted, so Phatak recommends isolating tasks in separate containers. That limits how much one task’s execution can affect another.

0:123:21
Suggest correction

This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.

0:12 · section reference included

The first container became a pet

The first Managed Agents architecture, shipped to early-access customers in December of the preceding year, placed all three responsibilities inside one container: the session log, the harness and sandbox execution. A session was the unit of work, and its history lived beside the process carrying out that work. This made the initial implementation straightforward. There were no service boundaries to design, everything was local, and a file edit could be a system call.

The cost appeared when the container failed. “We adopted a pet,” Phatak says. In the infrastructure analogy, a pet is an instance whose individual survival matters: when it gets sick, someone must nurse it back. Cattle are replaceable instances. Her database comparison makes the distinction concrete: losing a lone shard can take down the product, while a replica provides another instance to bring into service. The all-in-one agent container had become something the team could not easily discard.

Three operational problems exposed the coupling:

  • Ambiguous failures. A dropped packet and a dead container could look much the same from outside. Debugging required streaming into the container over a WebSocket to investigate what had happened.
  • Sensitive inspection. Customer data lived inside those containers, constraining the team’s ability to enter them and debug.
  • Private-network connections. Connecting to a customer’s MCP service inside a virtual private cloud meant peering networks or shipping the harness to the customer to run.

Local execution had removed service-design work at the beginning, but it also tied history, decision-making and execution to the same instance. Early-access feedback pushed the team toward a different division: preserve the work’s history while allowing the processes that think and act to be replaced.

4:515:21
Suggest correction

This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.

4:51 · section reference included

Separate the history, the brain and the hands

What needs to survive when an execution process disappears? The redesigned architecture answers with three separate interfaces. The session is an append-only log of everything that has happened. The brain is Claude together with the harness or agent loop. The hands are sandboxes and tools, including MCP calls, provisioned when needed and removed when the work is done. Separating these parts gives the log a different lifetime from the machinery doing the work.

A dead sandbox now appears to Claude as a failed tool call. Control returns to the model, which can decide to provision another sandbox or continue without it. Replacement is a possible response to failure, rather than an unconditional retry. If the harness itself dies, a new harness instance reads the session event log and resumes from the last event. The log carries continuity across the loss of the process.

The distinction between those two recovery paths matters. Sandbox failure becomes a decision within the agent’s work; harness failure requires another harness to recover the recorded history. In Phatak’s formulation, the session log is the part worth protecting because the other components can be brought back. This explains process recovery, though the recording does not specify how sandbox files are restored or how replay avoids repeating external side effects.

7:538:52
Suggest correction

This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.

7:53 · section reference included

Inject credentials after the sandbox sends its request

The redesign also moved credentials out of the sandbox. Previously, a token could live in the same environment where generated code ran. A malicious instruction asking Claude to print that token or write it to a file therefore had a valuable target. In the new design, an outbound request that needs authentication passes through a proxy, and the proxy injects the token before calling the external endpoint or MCP service.

Where does the credential enter the request? The flow below separates the sandbox’s request from the authenticated request sent onward. Claude and the sandbox do not receive the credential, so asking them to reveal it cannot extract a value they never saw. That addresses this credential-disclosure route; it does not establish that every action available through the authenticated service is safe from prompt injection.

The proxy adds the token outside the sandbox

SandboxSends a request requiring authentication. The credential never enters this environment.
Egress proxyInjects the token before calling the external destination.
External endpoint or MCPReceives the request with the token added by the proxy.
The sandbox initiates the call; the proxy supplies the credential on the outbound request to the external service.
Read the diagram as text
  • Sandbox. Sends a request requiring authentication. The credential never enters this environment.
  • Egress proxy. Injects the token before calling the external destination.
  • External endpoint or MCP. Receives the request with the token added by the proxy.
  • Sandbox → Egress proxy: Outbound request without the credential.
  • Egress proxy → External endpoint or MCP: Request with injected token.
9:089:38
Suggest correction

This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.

9:08 · section reference included

Keep the history intact and start inference sooner

An append-only log also separates stored history from the context supplied to the model. Compaction no longer needs to rewrite or discard the underlying event stream. One strategy can summarize the full history for the next model call; another can select only the last N events. Both operate over the same preserved events. This lets the team change context-management behavior as model capabilities change without changing the record of the session.

The same separation removes sandbox startup from the path to the first token. How does startup change when Claude can begin before its computer is ready? Inference starts immediately, and Claude provisions a sandbox only when it needs one. Phatak reports about a 90% reduction in time to first token from this architectural change. The recording gives no absolute latencies or workload breakdown, so the figure describes the team’s reported result rather than a latency guarantee.

The slide reports a 90% reduction in p95 time to first token and says inference starts immediately while hands are provisioned only when needed.Open full source frame
The slide reports a 90% reduction in p95 time to first token and says inference starts immediately while hands are provisioned only when needed.

One brain can also reach several kinds of hands: a sandbox container, a service inside a customer’s VPC, or an MCP server. These are alternative execution destinations available to the harness, rather than stages that every task must pass through. The architecture can accommodate different tools while leaving the agent loop replaceable.

The architectural lesson returns to the context-anxiety example: “harnesses encode assumptions, and assumptions can go stale.” Keeping the session, harness and execution interfaces separate lets those assumptions change locally. The team can replace the harness or change compaction while retaining the surrounding architecture.

9:5110:21
Suggest correction

This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.

9:51 · section reference included

Build Joke Teller from an environment and an agent definition

Before the hands-on portion, an audience question asks which interfaces actually make the design extensible. The answer stays concrete: the append-only session log, an interchangeable harness, and hands that can be sandboxes or other tools. The workshop then turns to Joke Teller, a small example that exposes the core API objects without requiring the later financial-agent exercise.

The setup has three steps, with different decisions in each:

  1. Create an environment. The environments API defines a sandbox template. It specifies installed packages and networking policy: unrestricted access, or restrictions to particular domains or MCPs.
  2. Create an agent. Name it Joke Teller, select a model, provide its system prompt and choose its tools. The example prompt is: “You're a comedian. Find a fresh joke on the topic. Deliver it well.” The basic agent tool set includes file-reading and file-writing capabilities.
  3. Create a session. Supply an agent ID and an environment ID. Together they identify the agent configuration and execution environment for this unit of work.

Creating the session does not start the task. A newly provisioned session is idle until an event arrives. The system prompt establishes how Joke Teller should behave, but the request for a particular joke comes later. That distinction separates configuring an agent from asking it to do work.

12:2513:38
Suggest correction

This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.

11:43 · section reference included

Use the event stream to start work, handle tools and stop

The joke request enters the session as a user.message: “tell me a joke about distributed systems.” The agent’s response then comes back through the event stream. This installment explains that exchange but does not present the resulting joke. The important change is that the idle session now has an input to act on.

How does application-owned code participate in that exchange? A custom tool lets the application handle execution itself. Claude places a custom tool-use event on the stream; the application listens for it, processes the request and sends a custom tool result back to Claude. The stream therefore carries both conversational input and the request/result exchange needed to connect the model to application behavior.

The two columns separate events the application sends, including custom-tool results, from agent events it receives, including custom-tool use.Open full source frame
The two columns separate events the application sends, including custom-tool results, from agent events it receives, including custom-tool use.

Other events expose lifecycle state and control:

  • session.error: reports an error encountered by the session.
  • Idle status: indicates the session is not working; Phatak notes that this typically coincides with not using a sandbox.
  • Interrupt: lets the application stop the session’s work when it is no longer wanted.

The recording ends at the console’s Managed Agents quick start, described as a guided tour for building the first agent. Multi-agent behavior and memory are named as topics for Gabe’s later portion, rather than developed here. By this point, the small example has made the architecture tangible: an environment defines where execution can happen, an agent defines behavior and tools, and a session receives the events that turn those definitions into work.

15:2715:39
Suggest correction

This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.

15:39 · section reference included

Resources

Transcript download
Full transcript