Anthropic now offers three materially different ways to build an agent:
- The Messages API gives direct model access and leaves the loop to the application.
- The Claude Agent SDK packages the Claude Code-style harness but runs inside infrastructure the developer operates.
- Claude Managed Agents persists agent definitions and sessions, hosts the harness, and can run tools in Anthropic-managed or self-hosted environments.
Around those surfaces, the platform is accumulating programmatic tool calling, MCP, Skills, memory stores, subagents, webhooks, scheduled deployments, effort and task budgets, and enterprise administration. This is not merely an API with more tools. It is an attempt to productize the generic execution layer around Claude.
The key architectural decision is therefore: which parts of the agent runtime should Anthropic operate, and which parts must remain inside your trust boundary?
Choose the surface before choosing the feature
| Surface | You operate | Anthropic operates | Best starting point for |
|---|---|---|---|
| Messages API | History, loop, retries, tools, state, sandbox, policy | Model inference and selected server tools | Fine-grained protocols, existing runtimes, regulated custom control |
| Agent SDK | Process, infrastructure, tool services, durable business state | Model inference; SDK supplies agent-loop abstractions | Claude Code-like agents in your environment |
| Managed Agents | Product logic, agent definition, policies, custom tool execution | Session, hosted harness, optional sandbox, built-in tools, compaction | Long-running and asynchronous agents with less infrastructure |
Anthropic’s Managed Agents migration guide makes the boundary explicit. Moving from a hand-written Messages loop removes conversation-history management and much orchestration plumbing. Moving from the Agent SDK changes where the harness runs. Neither migration transfers ownership of domain policy or accountability to Anthropic.
Messages remains the lowest-level contract
The Messages API is appropriate when the application needs to control every model turn, preserve an existing event model, run a deterministic workflow, or keep execution within a specialized security boundary.
Direct control is valuable when:
- a regulated action requires an application-owned state machine;
- a tool result must be validated before the model sees it;
- retries, idempotency, and compensation have business semantics;
- the context compiler uses proprietary retrieval and policy services;
- a workload must run across more than one model provider;
- traces need a provider-neutral schema.
The cost is engineering. You own context growth, compaction, tool loops, error recovery, cancellation, session storage, and observability. A while-loop demo is not a durable agent runtime.
The Agent SDK is a harness you still host
The Claude Agent SDK exposes the agent behavior behind Claude Code: tools, subagents, background tasks, plugins, and long-running execution. Anthropic’s Xcode integration demonstrates the intended portability. Xcode can host a Claude agent with documentation search, file modification, iterative execution, subagents, and MCP access without being Claude Code itself.
Use the SDK when Claude Code’s interaction model is close to your product but you need to own the process, network placement, and integration layer. The SDK does not eliminate the need for a durable workflow store, domain database, authorization service, or incident process.
Managed Agents hosts a versioned agent runtime
Claude Managed Agents is a beta service organized around four resources:
- Agent: model, system prompt, tools, MCP servers, and Skills.
- Environment: Anthropic-managed cloud sandbox or a self-hosted worker.
- Session: a running instance with durable history and filesystem state.
- Events: user messages, tool calls and results, approvals, status changes, and subagent activity.
Agents are reusable and versioned. Sessions can be started with initial events, interrupted, streamed, resumed, and observed through webhooks. The platform handles prompt caching, compaction, and selected runtime optimizations. Scheduled deployments can run agents on a recurring basis.
The beta header is a practical warning: behavior and schemas can change. Pin SDK versions, beta headers, model IDs, and agent versions together, and replay a regression suite before upgrading.
Decoupling brain, session, and hands is the core architecture
Anthropic’s Managed Agents engineering report explains why it separated the system into three interfaces:
- the brain is Claude plus the harness;
- the session is the append-only event history;
- the hands are sandboxes, MCP servers, and tools.
The separation provides failure isolation and flexibility. A stateless harness can start without waiting for a container. A sandbox can run in the customer’s infrastructure. Credentials can remain in a vault or be attached at a proxy instead of becoming visible to model-generated code. One brain can address multiple hands, and several brains can coordinate.
Anthropic reports that this design reduced median time to first token by about 60% and p95 by more than 90%. That is a company measurement on its own system, but the architectural lesson is independent: do not make durable state depend on the health of an execution container.
Programmatic tool calling turns Claude into a code orchestrator
Programmatic tool calling lets Claude write Python that invokes eligible tools inside Anthropic’s code-execution sandbox. The program can loop, branch, run calls concurrently, and reduce intermediate results before the model sees them.
The important context behavior is that intermediate tool results do not enter Claude’s context; only the program’s final output does. Anthropic reports typical token savings of 20–40% for production API requests containing 10–49 tool definitions when programmatic calling is enabled. Savings depend on workload shape.
Use it for:
- parallel lookups with structured aggregation;
- filtering large result sets before model review;
- deterministic loops over records;
- calculations and schema validation;
- conditional calls that do not require fresh semantic judgment.
Avoid it when each step depends on the model reinterpreting a result, when a durable business workflow owns the sequence, or when a write needs a visible approval boundary. Generated Python is still model output; restrict which tools may be called from code with allowed_callers and keep consequential authorization outside the script.
Tool search protects context as the catalog grows
Large tool catalogs waste context and reduce selection quality. Anthropic’s tool search supports deferred tool definitions. Claude searches a catalog and receives the full schema only for relevant tools.
Deferred definitions are excluded from the cached prompt prefix, so adding them does not invalidate an existing cache entry. This is a good example of context engineering becoming an API primitive: tool discovery, prompt-cache stability, and token cost are handled by one mechanism.
Tool search does not replace authorization. Discovery answers “which tool might help?” Policy answers “may this agent use it for this requester, tenant, data class, and action?”
MCP is both the integration plane and the trust boundary
Managed Agents and the Messages API can connect to remote MCP servers. Managed Agents supports private services through MCP tunnels, and Anthropic stores OAuth credentials in a vault so the sandbox does not need to see them directly.
MCP standardizes discovery and invocation. It does not make a server trustworthy. A production MCP program needs:
- an approved server and dependency inventory;
- workload identity and narrow scopes;
- reviewed tool names, descriptions, and schemas;
- explicit read/write/action classification;
- outbound data controls;
- result provenance and content-risk handling;
- timeouts, idempotency, and safe retries;
- revocation, versioning, and incident response.
Anthropic’s June MCP tunnel API change is useful for private connectivity, but a private network path is not an authorization policy.
Skills package procedural context
Agent Skills are directories containing SKILL.md plus supporting files. Anthropic provides document Skills for common PowerPoint, Excel, Word, and PDF work; developers can upload their own and attach them to a versioned agent.
Skills are valuable because they load task-specific instructions and assets on demand. They should be governed like code and configuration:
- review the source and supporting scripts;
- version and pin the artifact;
- test on representative tasks;
- restrict bundled credentials and network behavior;
- record which Skill version shaped each run;
- retire Skills when procedures change.
A Skill is executable institutional knowledge. Treating it as an unreviewed prompt file creates silent process drift.
Memory and Dreams introduce a second lifecycle
Managed Agents memory is in public beta. A memory store can persist information across sessions, while the Dreams research preview reads memories and session transcripts to merge duplicates, replace stale entries, and surface new insights. As of August 1, Dreams supports Opus 5 as well as Fable 5 and Sonnet 5.
This creates two different loops:
- The task loop reads context, acts, and produces an outcome.
- The memory loop decides what should survive, how it should be reorganized, and what should be removed.
Do not let an autonomous consolidation process become the only source of truth. Keep source references, distinguish model-authored inferences from verified facts, and make destructive memory changes reviewable or recoverable. A reorganized memory store should carry a lineage back to the inputs and transformation run.
Effort and task budgets control different things
Effort controls how much inference the model tends to spend on a turn. Managed Agents can set it in the persisted model configuration. Task budgets give Claude an advisory token allowance for an entire agentic loop, including reasoning, tool calls, results, and output, so the model can pace work and finish gracefully.
Neither is a billing cap by itself. A production system still needs hard organization and workflow spend limits, maximum tool calls, wall-clock deadlines, concurrency caps, and cancellation.
Use the controls together:
hard workflow budget
├─ model effort policy
├─ advisory task token budget
├─ max duration and tool calls
├─ subagent concurrency cap
└─ stop / escalate conditionsWhat the platform still does not own
Even with Managed Agents, the application remains responsible for:
- Intent and risk classification.
- Tenant and workload identity.
- Domain authorization and approval semantics.
- The correctness of custom tools and their side effects.
- Durable business state and idempotency.
- Outcome evaluation and release gates.
- Incident response, rollback, and accountability.
Anthropic can host the agent loop. It cannot define what “approved refund,” “valid trade,” “compliant disclosure,” or “safe production change” means for your organization.
A minimum production boundary
For a consequential Managed Agent, put an application-owned control layer around the service:
requester → intent/risk → context + policy → Managed Agent
↓
tools / MCP / sandbox
↓
decision record + outcome evalThe record should include the agent version, model and effort, prompt and Skill versions, memory snapshot references, selected tools, approvals, tool results, fallbacks, subagent events, final artifacts, and evaluation verdicts.
The durable takeaway
Anthropic is moving the reusable parts of Claude Code’s harness into the Claude Platform. Messages supplies direct control, the Agent SDK supplies a host-it-yourself harness, and Managed Agents supplies a hosted long-running runtime. Programmatic tools, MCP, Skills, memory, and budgets fill in the surrounding execution system.
The platform can remove substantial plumbing. The application still owns the meaning of authority, state, evidence, and success.