Lesson 1.3
Reference Architectures for Claude Solutions
The recurring production shapes for Claude systems, the platform features each one leans on, and the hosting and runtime choices that sit underneath them.
Most Claude solutions are variations on a small number of shapes. Knowing those shapes lets you recognise a scenario quickly, name the components a stakeholder will expect, and spot the risk that usually bites each one. This lesson catalogues the reference architectures the professional exam draws on and the runtime options beneath them.
The common layers
Whatever the use case, a production Claude system tends to have the same layers:
Clients (web, mobile, Slack, internal tools, CI)
|
Gateway / orchestration service <- auth, rate limiting, logging, prompt assembly
| model routing, caching policy, evals hooks
Model access <- Claude API | Bedrock | Vertex AI | Foundry
|
Tools and data <- MCP servers, internal APIs, databases,
Files API, retrieval index, server tools
|
Observability and governance <- traces, cost telemetry, audit log,
human review queue
The gateway is where architects earn their fee: it centralises credentials, enforces per-team budgets, pins prompt versions, and gives you one place to add caching and evaluation sampling. A system that calls the model directly from twenty client applications has no such place.
Shape 1: Knowledge assistant over enterprise documents
Users ask questions; the system answers from a controlled corpus with citations.
- Core features: document content blocks with citations enabled, Files API for repeated documents, prompt caching of the stable corpus or instructions, retrieval for corpora too large for the context window.
- Key decision: context stuffing versus retrieval. If the working set fits comfortably and is reused, cache it; if not, retrieve the top passages and still ask for citations so answers are verifiable.
- Usual risk: stale or unauthorised documents reaching the model. Enforce document-level access control at retrieval time, not in the prompt.
Shape 2: Document processing pipeline
High-volume extraction, classification or transformation of documents with no human in the loop per item.
- Core features: Message Batches API for cost and throughput, structured outputs or strict tool schemas for machine-readable results, token counting for budgeting, a smaller model tier where quality allows.
- Key decision: confidence routing. Extract a confidence or ambiguity flag in the schema and send low-confidence items to a stronger model or a human queue.
- Usual risk: silent schema drift when a document type changes. Guard with validation and a regression suite.
Shape 3: Conversational agent with tools
A chat or voice assistant that can act: look up an order, create a ticket, schedule a visit.
- Core features: tool use with narrowly scoped tools, MCP servers for enterprise systems, streaming for perceived latency, mid-conversation operator instructions where supported, compaction or summarisation for long sessions.
- Key decision: which tools can write. Read tools run freely; write tools either require explicit user confirmation or are executed by deterministic code after the model proposes them.
- Usual risk: prompt injection through tool results and retrieved content. Treat every tool result as untrusted data.
Shape 4: Autonomous coding or operations agent
Long-running tasks over a repository or an environment: implement a feature, triage a failing pipeline, run a migration.
- Core features: the Agent SDK (Claude Code as a library) with built-in file and shell tools, hooks for policy enforcement, subagents for parallel exploration, session persistence; or Managed Agents where you want Anthropic to run the loop and host the sandbox.
- Key decision: self-hosted harness versus managed runtime. Self-hosting gives full control over tools and network; Managed Agents removes loop and sandbox operations from your plate but constrains where code runs.
- Usual risk: unbounded cost and destructive actions. Use permission rules, approval hooks and budgets.
Shape 5: Analytical and reporting agent
Scheduled or on-demand analysis: pull data, compute, chart, write a report.
- Core features: server-side code execution for computation and file generation, Agent Skills for document formats, web search where external data is needed, scheduled deployments or your own scheduler.
- Key decision: where computation runs. Server-side code execution avoids shipping data to another sandbox but means the data must be sent to the model; a local tool keeps data in place but you operate the sandbox.
- Usual risk: confident but wrong numbers. Require the agent to show its working and validate against known totals.
Runtime and hosting matrix
| Option | Who runs the loop | Who hosts tools | Fits when |
|---|---|---|---|
| Messages API, your own loop | You | You | Maximum control, custom control flow |
| SDK tool runner | SDK helper | You | Standard agent loop over your tools without boilerplate |
| Agent SDK | Claude Code harness, in your process | You | Coding and filesystem agents, hooks, subagents |
| Managed Agents | Anthropic | Anthropic sandbox plus your tools | Persisted agent configs, long sessions, scheduled runs |
| Cloud platforms (Bedrock, Vertex AI, Foundry) | You | You | Existing cloud governance, billing and identity must be reused |
Feature availability differs by platform; always verify against the current availability tables in the Anthropic docs before committing.
Exam focus
- Be able to name the layers of a production Claude system and explain why a gateway layer exists.
- Match scenario cues to shapes: citations and corpus imply a knowledge assistant; volume and no interactivity imply Batches; acting on systems implies tools and MCP; repository work implies the Agent SDK.
- Know the difference between the SDK tool runner, the Agent SDK and Managed Agents in terms of who runs the loop and who hosts the tools.
- Each shape has a characteristic risk; the exam expects you to pair the architecture with its mitigation.
- Platform feature parity is not guaranteed; the professional answer is to check availability before design sign-off.
Check yourself
5 questions
1.An internal knowledge assistant answers employee questions from 30,000 HR and policy documents. Users complain that answers cite policies that do not exist. The current design retrieves the top chunks from a vector store and pastes them into the user message as plain text. Which change to the reference architecture MOST directly addresses the hallucinated citations?
2.A media archive needs to classify and summarise two million historical articles once, with results needed within a few days and no interactive users. The team's first prototype calls the Messages API synchronously from a loop and keeps hitting rate limits. Which reference architecture is MOST appropriate?
3.A product team wants a long-running research agent with its own file workspace, shell and code execution. They do not want to operate the agent loop or the sandbox infrastructure, they want agent configurations to be stored and versioned server-side, and they are using the first-party Claude API. Which option matches these requirements?
4.A conglomerate has eleven product teams building on Claude. Finance cannot attribute spend, security has found API keys committed to three repositories, and nobody can say which prompts are in production. Which reference architecture change BEST addresses all three problems?
5.A reference architecture for a customer-facing assistant has these layers: web client, API layer with streaming, orchestration service calling Claude with tools, a tool execution service that calls internal systems, and a conversation store. The security team asks where tool-call authorisation (which customer may perform which action) should be enforced. Which placement is CORRECT?