18  The Evolution of Agentic Surfaces: Building with Claude Managed Agents

Originally published June 10, 2026.

18.1 From Terminal to Platform

The story of Claude’s agentic surfaces in 2026 is a story of progressive decoupling. When Claude Code first shipped, the model, the tool-calling loop, the file system, and the terminal were all bound together in a single application. It was powerful, but it was monolithic. You could only build what the CLI exposed.

The Claude Agent SDK loosened that coupling. It separated the agent loop — the reasoning engine — from the Claude Code frontend, letting developers embed agentic behavior inside their own applications. You got the same underlying capability, but in a programmable package. Finance agents, research pipelines, and custom internal tools blossomed.

Managed Agents takes the decoupling one step further — and it is the step that matters most for production. The core insight is simple to state and profound in its consequences: decouple the brain from the hands.

The brain — Claude’s reasoning, tool selection, and planning — lives on Anthropic’s infrastructure. The hands — the actual execution environment where commands run, files are written, and APIs are called — lives in a managed or self-hosted container that you control. The two communicate through a well-defined session protocol, but they no longer need to share a process, a machine, or even a trust boundary.

This separation unlocks everything that follows in this chapter.

18.2 Why Decoupling Matters

Consider the traditional architecture for an AI coding agent. The model API is called from your laptop or server. That same machine holds your source code, your credentials, your network access. The agent loop runs wherever the code runs. When the model decides to execute a shell command, it executes on the machine that holds the keys.

This creates a persistent tension. You want the agent to be capable — which means giving it broad access to files, networks, and tools. But you also want it to be safe — which means limiting what it can touch. In a coupled architecture, every capability is also a risk surface.

Concern Coupled (Claude Code) Decoupled (Managed Agents)
Model inference Local or direct API Anthropic-managed
Execution environment Your machine Sandboxed container
Credentials On the executing machine Injected at runtime, never persisted
Session persistence Tied to terminal session Durable, resumable
Scaling One session per terminal Many concurrent sessions
Trust boundary Blurred Explicit and enforced

Managed Agents resolves the tension by making the trust boundary explicit. The sandbox sees only what it needs to see to do its job. Credentials are injected through envelope encryption and are never written to disk inside the container. When the task completes, the container can be torn down entirely.

18.3 Three Resources

The Managed Agents API is built around three primary resources. Understanding how they relate is the key to building effectively on the platform.

18.3.1 1. Agents (Configuration)

An agent is a configuration object. It describes what the agent is: its system prompt, its model, its allowed tools, its MCP servers, its skills, and any default parameters. Think of it as a job description. An agent does not run; an agent is invoked.

agent:
  name: "release-preflight"
  model: "claude-opus-4-6"
  system_prompt: |
    You are a release engineering agent. Verify that the
    current branch passes all tests, the changelog is
    updated, and the version bump is correct.
  tools:
    - bash
    - file_read
    - file_write
    - git
  mcp_servers:
    - github
    - slack
  max_turns: 50

Agents are versioned. When you update a prompt or add a tool, you create a new version. Old sessions continue to reference the version they were started with, so in-flight work is never broken by a configuration change.

18.3.2 2. Environments (Execution)

An environment is the execution context — the sandbox where the agent’s actions actually take place. It is the “hands.” Environments come in two flavors:

  • Anthropic-managed containers: Fully hosted, auto-scaling, zero infrastructure to manage. Anthropic handles provisioning, scaling, and teardown. You pay for compute while the environment is active.
  • Self-hosted containers: You run the environment runtime on your own infrastructure — your cloud account, your VPC, your bare metal. Anthropic’s control plane orchestrates, but the execution stays inside your perimeter. This is essential for organizations with strict data residency or compliance requirements.

Both flavors expose the same interface to the agent. The brain does not know (or care) where its hands live.

Tip

Choose Anthropic-managed containers for speed of development and automatic scaling. Choose self-hosted containers when you need data residency control, private network access to internal services, or compliance certifications that require you to own the compute.

Environments are ephemeral by default but can be persisted. A persisted environment retains its filesystem state across sessions, which is useful for agents that work on long-lived codebases or need to accumulate context over time.

18.3.3 3. Sessions (Event Log)

A session is the running record of a specific invocation of an agent within an environment. It is an append-only event log. Every message, every tool call, every tool result, every intermediate reasoning step is recorded as an event in the session.

Sessions are the connective tissue. They are what make agents resumable, observable, and debuggable.

from anthropic import Anthropic

client = Anthropic()

# Create a session
session = client.agents.sessions.create(
    agent_id="release-preflight-v3",
    environment_id="prod-env-01",
    initial_message="Run preflight checks on the release branch."
)

# Stream events as the agent works
for event in client.agents.sessions.stream(session.id):
    if event.type == "tool_call":
        print(f"Calling: {event.tool_name}({event.arguments})")
    elif event.type == "tool_result":
        print(f"Result: {event.result[:200]}")
    elif event.type == "message":
        print(f"Claude: {event.content}")

Because sessions are durable, you can:

  • Resume a session after disconnection. The agent picks up exactly where it left off.
  • Replay a session to understand what happened. Every decision is traceable.
  • Branch a session to explore alternative approaches from a specific point.
  • Share a session with a colleague for collaborative debugging.

18.4 The Benefits in Practice

Managed Agents was not just an architectural refinement. It delivered measurable improvements across security, performance, and reliability.

18.4.1 Credentials Kept Out of the Sandbox

In a coupled architecture, credentials live on the same machine as the agent’s execution environment. If a prompt injection attack convinces the agent to exfiltrate data, the credentials are right there.

Managed Agents uses envelope encryption to solve this. Credentials are stored encrypted in Anthropic’s key management service. When an agent’s environment needs a credential — say, an API token to call an internal service — the following happens:

  1. The environment requests the credential from the control plane.
  2. The control plane checks that the agent’s policy permits this credential for this action.
  3. If permitted, the credential is decrypted and injected into the environment’s memory.
  4. The credential is never written to disk inside the container.
  5. When the environment is torn down, the credential ceases to exist.

This means that even a fully compromised sandbox — one where an attacker has root access to the container — cannot extract credentials. They exist only transiently, in memory, for the duration of the task that needs them.

Note

Envelope encryption means the data encryption key (DEK) that protects your credentials is itself encrypted by a key encryption key (KEK) that lives in a hardware security module. The sandbox never sees the KEK. Even if the container is captured, the credentials remain encrypted at rest.

18.4.2 60% Latency Reduction

Managed Agents redesigned the execution pipeline to minimize round trips. In the previous architecture, every tool call required a separate API request to the model, adding network latency on each iteration of the agent loop.

The new architecture batches tool calls, streams responses, and co-locates the model inference with the execution environment where possible. The result:

Metric Before (Agent SDK) After (Managed Agents) Improvement
p50 latency Baseline 40% lower —
p90 latency Baseline 55% lower —
p95 latency Baseline 60% lower —
p99 latency Baseline 50% lower —

The latency improvements are most pronounced for complex, multi-step tasks — exactly the kind of work that agents are built for. A task that requires 30 tool calls used to accumulate latency across 30 sequential round trips. Managed Agents reduces both the number of round trips and the per-trip latency.

18.4.3 Reliable Persistent Sessions

In the Claude Code CLI, a session lives as long as your terminal is open. Close the terminal, and the session is gone (or frozen in a state that may or may not resume cleanly). This is fine for interactive development but unacceptable for production agents that need to run for hours or days.

Managed Agents sessions are designed for durability:

  • Automatic checkpointing: The session state is checkpointed after every tool call. If the environment crashes, the session resumes from the last checkpoint.
  • Network resilience: If the connection between the brain and hands drops, the session pauses and automatically resumes when connectivity returns.
  • Long-running execution: Sessions can run for hours, days, or even weeks. A research agent that monitors a data pipeline can run continuously, with the session log serving as an audit trail.

18.4.4 Anthropic-Managed or Self-Hosted

The choice between managed and self-hosted environments is not binary — you can mix them. A common pattern:

  1. Development and testing: Use Anthropic-managed containers for fast iteration.
  2. Staging: Use self-hosted containers in your cloud account, configured to mirror production.
  3. Production: Use self-hosted containers with full network isolation, private connectivity to internal services, and compliance certifications.

The same agent configuration works across both. You develop once and deploy anywhere.

18.5 Building Your First Managed Agent

Here is a complete example of creating and running a managed agent that performs code review on a pull request.

from anthropic import Anthropic

client = Anthropic()

# Step 1: Define the agent
agent = client.agents.create(
    name="pr-reviewer",
    model="claude-sonnet-4-6",
    system_prompt="""You are an expert code reviewer. For each PR:
1. Check for bugs, security issues, and style violations.
2. Verify that tests exist for new code.
3. Ensure the changelog is updated.
4. Leave constructive comments on the PR.
Be thorough but kind.""",
    tools=["bash", "file_read", "git", "http_request"],
    mcp_servers=["github"],
    environment_type="managed",  # or "self-hosted"
)

# Step 2: Create an environment
environment = client.agents.environments.create(
    agent_id=agent.id,
    persist=False,  # ephemeral
    cpu="2-vcpu",
    memory="4-gb",
)

# Step 3: Start a session
session = client.agents.sessions.create(
    agent_id=agent.id,
    environment_id=environment.id,
    initial_message=f"""Review PR #1234 in the repo.
Clone the repo, read the diff, and leave your review.""",
)

# Step 4: Wait for completion
result = client.agents.sessions.wait(session.id, timeout=600)
print(f"Review complete: {result.summary}")

18.6 Architectural Decision Guide

When should you reach for Managed Agents versus the Agent SDK versus Claude Code?

Surface Best For Infrastructure Burden
Claude Code Interactive development, pair programming None (runs on your machine)
Agent SDK Custom agent apps, embedded agents, full control You manage execution
Managed Agents Production agents at scale, multi-tenant platforms, long-running automation Anthropic manages (or you self-host env)
Tip

A practical heuristic: if your agent needs to run unattended, serve multiple users, or operate in a regulated environment, choose Managed Agents. If you are building a tool for yourself or a small team and want maximum flexibility, the Agent SDK gives you more direct control. If you are coding interactively, use Claude Code.

18.7 The Decoupled Future

Managed Agents represents a architectural commitment that will shape everything Anthropic builds next. By separating the brain from the hands, the platform creates clean interfaces at every layer:

  • Model upgrades can happen without touching execution environments.
  • Environment changes (new runtimes, new networks) don’t affect agent configurations.
  • Session logs become a universal debugging and auditing format.
  • Security policies can be enforced at the boundary between brain and hands, regardless of what either side does internally.

The trajectory is clear: agentic surfaces will continue to specialize. The brain will get smarter, the hands will get more dexterous, and the space between them — where security, observability, and control live — will get richer. Managed Agents is the foundation that makes that specialization possible.

18.8 Key Takeaways

  • Managed Agents decouples the brain (Claude’s reasoning) from the hands (the execution environment), creating a clean, enforceable trust boundary.
  • Three resources define the API: agents (configuration), environments (execution), and sessions (the durable event log).
  • Credentials are kept out of the sandbox using envelope encryption — they are injected into memory at runtime and never persisted to disk inside the container.
  • Latency drops significantly: up to 60% reduction at p95, with the largest gains on complex multi-step tasks.
  • Sessions are durable and resumable: checkpointed after every tool call, resilient to network interruption, and capable of running for days.
  • Choose Anthropic-managed containers for speed, self-hosted containers for control — and mix them across development, staging, and production.
  • The same agent configuration runs in any environment type, so you develop once and deploy anywhere.
  • Decoupling is the architectural commitment that enables independent evolution of models, execution environments, and security controls.