Inside a Production Claude Agent: The Full Architecture

Most teams meet Claude through a chat box and assume the agent is the model. In production it is the opposite: the model is one component inside a running system, and the system is what makes the intelligence useful. If you have ever watched a demo agent work flawlessly and then collapse the moment you wire it to real data, you have already felt the gap. The model did not get worse — the architecture around it was never built. This post walks the whole stack of a Claude agent in production, from the moment a request lands to the moment a verified result comes back, and shows where each piece lives and why it exists.

What a Claude agent actually is

A Claude agent is a control loop wrapped around the model. A production Claude agent is a system that repeatedly sends Claude an assembled context, lets the model decide on an action — usually a tool call or a final answer — executes that action in a sandboxed runtime, and feeds the result back until the task is done. The model supplies judgment; the surrounding code supplies state, tools, guardrails, and the loop itself. Strip the loop away and you have a very good autocomplete. Add the loop and you have something that can read a ticket, query three systems, write a patch, and check its own work.

The reason this matters architecturally is that nearly every failure mode you will hit lives in the surrounding system, not the model. Context that is too noisy, tools that return ambiguous errors, a loop that never terminates, state that silently drifts between turns — these are engineering problems. Claude 4.x models (Opus 4.8, Sonnet 4.6, Haiku 4.5) are strong enough that the bottleneck has moved decisively from raw reasoning to how well you feed and constrain that reasoning.

The five layers, end to end

I find it cleanest to think in five layers stacked between the request and the model. The ingress layer receives the task and normalizes it: a chat message, a webhook, a queued job, or a parent agent's instruction. The context assembly layer builds the prompt for this turn — system instructions, relevant history, retrieved documents, available tool schemas, and any loaded skills. The model layer is the call to Claude itself, which returns either text or a structured tool-use request. The tool runtime executes whatever the model asked for against MCP servers, internal APIs, or local scripts. Finally the orchestration layer owns the loop: it decides whether to continue, retry, escalate, or stop.

The trick is that data flows in a cycle, not a line. A tool result re-enters context assembly, which produces a new prompt, which produces a new action. Every pass through the cycle is a chance for the context to grow stale or bloated, which is why the context assembly layer is where senior engineers spend most of their tuning time.

flowchart TD
  A["Request arrives at ingress"] --> B["Context assembly: system + history + tools + skills"]
  B --> C["Claude model call"]
  C --> D{"Tool use or final answer?"}
  D -->|Final answer| H["Verify & return result"]
  D -->|Tool use| E["Tool runtime executes call"]
  E --> F["MCP server / API / script returns data"]
  F --> G["Append result to context"]
  G --> B

How context assembly keeps the agent grounded

The context assembly layer is the heart of the architecture because it is the only place where you fully control what the model sees. On each turn it composes a fresh context window from durable pieces. The system prompt holds the agent's role, constraints, and output contract — this rarely changes and is an ideal candidate for prompt caching, which lets Claude reuse the tokenized prefix across calls and cut both latency and cost. Below that sits working memory: the relevant slice of conversation history plus any tool results that still matter. Then come the tool schemas and skills the agent is allowed to use right now.

What separates a robust agent from a fragile one is selective assembly. You do not dump the entire history into every turn; with a 1M-token window you can, but you should not, because irrelevant tokens dilute attention and raise cost. Instead the layer prunes resolved sub-tasks, summarizes long-running threads, and pulls only the documents that this specific step needs through retrieval. Skills make this dynamic: rather than loading every instruction set up front, Claude loads a skill's full content only when the task signals it is relevant, keeping the baseline context lean.

The tool runtime and the MCP boundary

When Claude emits a tool-use block, the tool runtime takes over. This is a hard architectural boundary worth respecting: the model never touches your database or your filesystem directly. It produces a structured intent — a tool name and a JSON argument object validated against the schema you advertised — and your runtime decides whether and how to execute it. Model Context Protocol is the open standard (introduced in November 2024) that formalizes this boundary, letting any MCP-compatible server expose tools and resources to Claude through one consistent interface.

Architecturally, MCP servers become independently deployable units. A GitHub MCP server, a Postgres MCP server, and a custom internal-CRM server can each run as their own process, scale on their own, and fail in isolation. The runtime calls them, captures structured results or errors, and hands a clean string back to context assembly. This separation is why mature Claude deployments feel less like a monolith and more like a small distributed system with the model as a stateless reasoning service in the middle.

The orchestration loop and termination

The orchestration layer answers a deceptively hard question on every turn: are we done? Naive loops run until the model stops asking for tools, which works until a confused agent loops forever or burns your budget retrying a broken call. Production loops add explicit termination conditions — a maximum number of turns, a token budget, a wall-clock deadline, and a success check that inspects the final answer against the task contract. When a tool fails, the loop decides between an automatic retry with backoff, a reformulation prompt that tells Claude what went wrong, or an escalation to a human or a parent agent.

This is also where multi-agent architectures appear. An orchestrator agent can decompose a large task and spawn subagents, each with its own context and tool set, then merge their outputs. The pattern is powerful but expensive: a multi-agent run typically consumes several times more tokens than a single agent doing the same work, because each subagent carries its own context. The architectural rule of thumb is to reach for subagents only when the work genuinely parallelizes or when isolating context between concerns improves quality enough to justify the cost.

Observability that makes the whole thing debuggable

None of the layers above are debuggable unless you instrument them. Because the agent's behavior emerges from the loop, a single log line tells you almost nothing; you need the full trace. For every turn, capture the assembled context size, the model's chosen action, the exact tool arguments, the tool's raw result, and the loop's decision. Store these as a structured trace keyed to a task ID. When an agent does something baffling in production, the trace almost always reveals that context assembly fed it a stale value or a tool returned a misleading error — not that the model reasoned poorly.

Good observability also feeds your evals. The same traces you collect for debugging become the dataset you replay to check whether a prompt change or a model upgrade improved or regressed behavior. In a well-built Claude system, the architecture and the evaluation harness share the same plumbing, and that shared plumbing is what lets a team ship changes to a live agent without holding its breath.

Frequently asked questions

Is the agent the model or the surrounding code?

Both, but the surrounding code is what makes it an agent. The model provides reasoning and decides on actions; the loop, tool runtime, context assembly, and guardrails turn those decisions into a reliable system. In production, most of your engineering effort goes into the code around the model.

Where does MCP fit in the architecture?

MCP sits at the tool boundary. It is the standard interface between Claude's tool-use requests and the external systems that fulfill them, letting you expose databases, APIs, and services as independently deployable MCP servers the runtime can call.

How big should the context window get in practice?

Claude Code and the latest models support up to a 1M-token window, but using all of it on every turn is usually a mistake. Assemble the smallest context that fully answers the current step; prune resolved work and retrieve only relevant documents to keep attention sharp and cost down.

When should I add subagents?

Add them when work genuinely parallelizes or when isolating context between concerns clearly improves quality. Because multi-agent runs use several times more tokens, treat each subagent as a deliberate cost, not a default.

Bringing agentic AI to your phone lines

The same layered architecture — context loop, tool runtime, MCP boundary, orchestration — is exactly what powers CallSphere's voice and chat agents, which answer every call and message, use tools mid-conversation, and book real work around the clock. See the architecture running live at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.