Claude Agent SDK Architecture Diagram: Multi-Agent Systems (2026)

How to diagram Claude Agent SDK systems. Covers orchestrators, subagents, tool use, MCP integration, human-in-the-loop gates, and multi-agent coordination patterns with ready-to-use prompt templates.

Ryan·Senior AI Engineer

·Last updated June 6, 2026

A Claude Agent SDK architecture diagram visualizes how AI agents built with Anthropic's Agent SDK are structured, how they delegate work to subagents, which tools and MCP servers each agent can access, and where human oversight gates interrupt automated execution. As teams move from single-model API calls to full multi-agent pipelines, having a clear diagram of agent topology becomes as important as having a service diagram for a microservices backend.

This guide covers the core building blocks of the Claude Agent SDK, the most common deployment patterns, and prompt templates you can paste directly into ArchitectureDiagram.ai to generate accurate diagrams in seconds.

What is the Claude Agent SDK?

The Claude Agent SDK is Anthropic's framework for building agentic applications on top of Claude models. Rather than calling the Messages API once and returning a response, an agent runs in a loop: it receives a task, decides which tools to call, receives tool results, continues reasoning, and repeats until the task is complete or an interrupt condition is met.

The SDK handles the core agentic loop so you don't have to build it from scratch: token budgeting, tool-call dispatch, result injection, loop termination logic, and structured output parsing. It also provides first-class support for spawning subagents — Claude instances that a parent orchestrator creates and delegates subtasks to, collecting their results asynchronously.

Architecturally, the Claude Agent SDK sits between raw API calls (where you manage state and loops yourself) and opinionated frameworks like LangGraph or CrewAI (which impose their own graph abstractions). The SDK is intentionally minimal: it gives you the loop, the tool registry, and the subagent spawning primitives, then gets out of the way.

Core components of a Claude Agent SDK system

Orchestrator agent

The orchestrator is the top-level Claude agent that receives the user's original task. It plans, decomposes the task into subtasks, decides which subagents or tools to invoke, and synthesizes the final result. In your diagram, the orchestrator is the entry point and should sit at the top of the hierarchy. It holds the overall task context and is typically running a larger model (e.g., claude-opus-4-8) while subagents might use claude-sonnet-4-6 or claude-haiku-4-5 for cost efficiency.

Subagents

Subagents are Claude instances spawned by the orchestrator to handle specific subtasks in parallel or sequentially. Each subagent has its own tool registry, its own context window, and optionally its own MCP server connections. Subagents are stateless from the orchestrator's perspective — the orchestrator passes them a task description and receives a structured result, without needing to know how the subagent accomplished it. This isolation is what makes multi-agent systems compositional: you can swap, upgrade, or replace individual subagents without changing the orchestrator.

Tool registry

Every agent in the SDK has a tool registry — the set of tools it can call. Tools are typed function definitions that the SDK serializes into the model's tool-use prompt. In a multi-agent architecture, different agents have different tool registries. The orchestrator might have high-level tools like spawn_subagent and wait_for_results, while a research subagent has tools like web_search, fetch_url, and extract_text. Your diagram should show which tools each agent can access — this is the key security and capability boundary in the system.

MCP server connections

Claude Agent SDK agents can connect to MCP (Model Context Protocol) servers to access external systems: databases, file systems, APIs, code execution environments, and more. An agent's tools can be a mix of locally defined functions and tools surfaced from MCP servers. In your diagram, show MCP server connections as a separate layer below the agents — each agent-to-MCP connection represents a distinct trust boundary and set of capabilities. See the MCP architecture diagram guide for detailed patterns.

Human-in-the-loop (HITL) gates

The Agent SDK supports interrupt conditions — points in the agentic loop where execution pauses and waits for human input before continuing. In your architecture diagram, these gates are first-class components: show them as explicit decision nodes between the agent and any irreversible action (sending an email, deploying code, deleting data, spending money). The pattern is: agent proposes action → HITL gate surfaces it to a human → human approves/rejects/ modifies → agent continues or stops.

Memory and state store

Agents using the Claude Agent SDK are stateless between runs by default — their context window is their working memory. For persistent state across runs, teams add an external memory store: a database, a vector store, or a knowledge graph that the agent reads from and writes to via tools. Your diagram should explicitly show this distinction: what lives in the agent's context window (ephemeral) vs. what is persisted to an external store (durable). See the AI memory architecture guide for detailed patterns.

Prompt templates for common Claude Agent SDK patterns

Single agent with tools

"A single Claude claude-sonnet-4-6 agent receives a research task from the user. The agent has four tools in its registry: web_search (calls a search API), fetch_url (downloads and extracts text from a URL), run_python (executes Python in a sandboxed E2B environment), and write_file (writes results to a local output directory). The agent runs in a loop: plan, call tools, observe results, continue. It terminates when it has produced a structured research report and written it to the output directory. Show the agent's tool calls as numbered sequence steps."

Orchestrator with parallel subagents

"A claude-opus-4-8 orchestrator agent receives a complex competitive analysis task. It decomposes the task and spawns three claude-sonnet-4-6 subagents in parallel: Subagent A (web research) has web_search and fetch_url tools; Subagent B (data analysis) has a PostgreSQL MCP server and a Python execution MCP server; Subagent C (report writing) has a filesystem MCP server and a Google Docs MCP server. The orchestrator uses a spawn_subagent tool to launch all three, then waits on a collect_results tool that returns when all three complete. The orchestrator synthesizes the three results into a final executive summary and passes it back to the user. Show agents as swim lanes with parallel execution brackets."

Agent with human-in-the-loop approval gate

"A Claude agent automates code review and deployment. It connects to a GitHub MCP server (can read PRs, post comments, and approve merges) and a CI/CD MCP server (can trigger builds and deployments). The agent reads open PRs, runs static analysis, and posts a review comment autonomously. However, before it approves a PR merge or triggers a production deployment, execution pauses at a HITL gate: the agent serializes its proposed action and rationale to a Slack approval channel. A human engineer clicks Approve or Reject in Slack — the response is delivered back to the agent via a webhook tool. Only on Approve does the agent proceed with the merge or deployment. On Reject, the agent adds the engineer's reason to its context and re-evaluates. Show the HITL gate as a red diamond decision node."

Persistent agent with memory store

"A customer support Claude agent maintains long-term memory across sessions. Before each conversation, the agent calls a recall_memory tool that queries a pgvector store for relevant past interactions with this user (top-5 semantic matches by user_id). During the conversation, the agent has access to: a knowledge_base tool (searches a Supabase vector store of product documentation), a create_ticket tool (writes to a Zendesk MCP server), and a save_memory tool (upserts the conversation summary and key facts to the pgvector store at session end). Show the memory store as a persistent component with bidirectional arrows for read (recall) and write (save) operations."

Claude Agent SDK pattern reference

Pattern	When to use	Key diagram elements
Single agent + tools	Task fits in one context window, sequential tool use	Agent loop, tool registry, termination condition
Parallel fan-out	Independent subtasks that benefit from parallelism	Orchestrator, N subagents, collect_results barrier
Sequential pipeline	Subtasks have strict dependencies (A → B → C)	Chain of subagents, output-as-input arrows
HITL approval gate	Irreversible actions requiring human sign-off	Agent, gate node, notification channel, resume trigger
Supervisor/subagent	Tasks need specialized agents; orchestrator coordinates	Supervisor with routing logic, specialist subagents
Memory-augmented loop	Agent needs context beyond one context window	Agent, recall tool, memory store, save tool

What a Claude Agent SDK diagram must show

Model assignments: Label each agent with its Claude model variant. Orchestrators typically use Opus for better planning; subagents use Sonnet or Haiku for throughput and cost.
Tool registries per agent: Show which tools each agent can invoke. This is the most important security surface — a tool is a capability grant.
Subagent lifecycle: Make clear when subagents are spawned, whether they run in parallel or sequentially, and when the orchestrator waits for their results.
MCP server connections: Show which agents connect to which MCP servers and via which transport (stdio vs. HTTP+SSE).
HITL gates: Every interrupt condition should be a visible decision node with both the approval path and the rejection/modification path shown.
State boundaries: Distinguish ephemeral context-window state from durable external state (memory stores, databases).
Token budget: For long-running orchestrators, note the token budget strategy — whether the orchestrator compresses its context, uses extended thinking, or delegates to subagents precisely to avoid context exhaustion.

Claude Agent SDK vs. other agent frameworks

Framework	Abstraction level	Diagram style	Best for
Claude Agent SDK	Low — minimal primitives	Hierarchical agent trees, tool registries	Claude-native, production systems needing control
LangGraph	Medium — graph-based state machines	Directed graphs, nodes, conditional edges	Complex branching workflows with checkpointing
CrewAI	High — role-based crew abstraction	Agents as role swimlanes, tasks as steps	Collaborative multi-role agent teams
OpenAI Agents SDK	Low — similar primitives to Claude SDK	Agent handoffs, tool calls, guardrails	OpenAI-native multi-agent systems
Temporal + Claude	Infrastructure — durable execution engine	Workflows, activities, signals, timers	Long-running agents needing replay/fault tolerance

Frequently asked questions

What is the Claude Agent SDK?

The Claude Agent SDK is Anthropic's framework for building agentic applications on top of Claude models. It provides an agentic loop runtime, a tool registry, subagent spawning primitives, and human-in-the-loop interrupt support. Unlike raw API calls, the SDK manages the iterative reasoning-and-tool-use cycle so engineers can focus on defining tools and agent topology rather than loop management boilerplate.

How do I diagram a multi-agent system with the Claude Agent SDK?

Start with the orchestrator at the top. Draw each subagent as a separate box, labeled with its model variant and purpose. Show each agent's tool registry as a list inside its box (or as a connected component). Draw MCP server connections below the agents. Show human-in-the-loop gates as diamond decision nodes between the agent and any irreversible action. Use swim lanes for parallel subagents and sequence arrows for sequential ones.

What is the difference between an orchestrator and a subagent?

An orchestrator receives the user's high-level goal, plans the approach, and delegates subtasks to subagents or tools. It synthesizes results and returns the final answer. A subagent receives a specific, well-scoped subtask from the orchestrator, executes it using its own tools, and returns a structured result. Subagents typically do not know about the broader task context — they just complete their assigned piece. This separation keeps context windows manageable and allows subagents to be replaced independently.

Ready to try it yourself?

Start Creating - Free