The Claude Agent SDK Mental Model
The Claude Agent SDK is Anthropic's library for building production AI agents in Python or TypeScript.
It was renamed from "Claude Code SDK" in 2025, and that rename is the fastest way to understand what it actually is.
Claude Code, the command-line coding agent, is built on the exact same primitives this SDK exposes to you: a tool-use loop, a set of built-in tools, subagents, sessions, and MCP client support.
Learning this SDK is learning how Claude Code works internally, then getting to point that same machinery at whatever problem you're solving instead of just software engineering.
This page builds the mental model that the rest of the section assumes: what the loop actually does on each turn, how built-in tools and subagents fit into it, and where sessions and MCP servers attach.
Summary
- Core Idea: The SDK wraps a model call in a tool-use loop, hands that loop a scoped set of tools (built-in, subagent, or MCP), and lets the loop run until the agent produces a final answer or hits a stopping condition.
- Why It Matters: A single prompt-response call cannot read a file, run a command, or delegate a subtask; the loop is what turns a language model into something that can actually act on a codebase or system.
- Key Concepts: tool-use loop, built-in tools, subagents, sessions, human-in-the-loop checkpoints, MCP client.
- When to Use: Any task that needs the model to read/write files, execute commands, browse the web, or coordinate multiple independent workstreams, not just generate text.
- Limitations / Trade-offs: More capability means more surface area to secure; every tool you enable is something the loop can now do without a human watching each step, unless you add checkpoints.
- Related Topics: query() basics, tool scoping, subagent delegation, session persistence, MCP servers.
Foundations
At its simplest, calling a language model is one request and one response.
You send a prompt, the model returns text, and nothing in the world changes as a result.
The Claude Agent SDK exists because most real work is not that shape.
Real work usually means "look at this file, decide what to change, make the change, check that it worked" - a sequence of actions, not a single guess.
The SDK's answer to that gap is the tool-use loop: you start it with a query()-style call, and instead of returning after one response, the loop keeps running as long as the model keeps deciding it needs to call a tool.
On each turn the model either produces a final answer or asks to invoke a tool, the SDK executes that tool and feeds the result back in, and the model gets another turn with that new information available.
A simple analogy is a contractor working from a blueprint versus one just describing the house over the phone.
A raw model call is the phone description: detailed, but nothing gets built.
The tool-use loop is the contractor actually picking up tools, using them, and checking the result before deciding what to do next.
The SDK ships several categories of capability that plug into this loop, and understanding what each category is for is most of what you need before writing your first agent.
Built-in tools cover file editing, bash execution, web search, and web fetch, out of the box, no third-party wiring needed.
Subagents are child agents with their own isolated context that a parent agent can delegate work to, useful when a task splits into independent pieces.
Sessions let an agent's conversation and tool-call history persist across process runs, so a second invocation can resume instead of starting from nothing.
MCP client support lets the loop call tools that live outside the SDK entirely, on a local process or a remote server, through the Model Context Protocol.
Mechanics & Interactions
The loop's basic shape is always the same: decide, act, observe, repeat.
The "decide" step is the model choosing, based on the conversation and prior tool results so far, whether to call a tool or produce a final answer.
The "act" step is the SDK actually executing whatever the model asked for, whether that's a built-in tool, a subagent invocation, or an MCP tool call.
The "observe" step feeds the result of that action back into the conversation as new context, which is what makes the next "decide" step better informed than the last one.
This is exactly the loop Claude Code runs when it edits a file for you in the terminal: read, decide, edit, check the diff, decide again.
Where the categories interact is in how each one changes what "act" can do.
Built-in tools are the loop's default hands: file edit gives it the ability to change what's on disk, bash gives it a shell, web search and web fetch give it a way to pull in information beyond its training data.
None of these are mandatory; a production agent typically enables only the subset the task actually needs, because every enabled tool is something the loop can invoke without asking first, unless you add a checkpoint.
from claude_agent_sdk import query, AgentOptions
options = AgentOptions(
allowed_tools=["file_edit", "bash"], # scoped, not "everything on"
permission_mode="default", # loop pauses before risky actions
)
result = query("Fix the failing test in tests/test_orders.py", options=options)Subagents change the shape of "act" from "run one tool" to "hand this whole subtask to a separate agent and wait for its result."
Each subagent gets its own context window and its own tool access, which means a parent agent working on a large task can fan work out to several subagents that don't pollute each other's context or step on each other's intermediate reasoning.
That isolation is also the main reason to reach for a subagent instead of just adding another tool call: independent workstreams stay independent, and you can run them in parallel.
Human-in-the-loop checkpoints attach to the "act" step specifically, not the whole loop.
A checkpoint pauses execution right before a specific tool call goes out, typically one flagged as destructive or irreversible (deleting files, pushing to a remote, spending money), and waits for approval before letting "act" proceed.
Sessions operate across loop invocations rather than inside a single one.
A session ID captures the conversation and tool-result history at the point a run ends, and passing that ID into a later query() call resumes the loop from there instead of starting cold, which matters for long-running or multi-step agent tasks that don't fit in one process lifetime.
MCP client support widens what "act" can reach without you writing custom tool code yourself.
An MCP server, whether it's a local stdio process or a remote HTTP endpoint, exposes tools with the same shape as built-in tools, so once you register one, the loop can call it exactly like it calls file edit or bash.
Advanced Considerations & Applications
The mental model above holds together well until you start composing pieces, and that's where most production design decisions actually live.
A parent agent with subagents is still one tool-use loop at the top: each subagent invocation is just another tool call from the parent's perspective, and the subagent runs its own internal loop underneath, with its own decide-act-observe cycle and its own tool scope.
That nesting is why subagents compose cleanly with checkpoints and sessions: a checkpoint on the parent doesn't automatically apply inside a subagent, and a subagent typically does not inherit the parent's session unless you explicitly wire that up.
Tool scoping interacts with checkpoints in a way that's easy to get backwards: scoping decides what the loop is even capable of calling, while checkpoints decide which of those allowed calls still needs a human to say yes.
A narrowly scoped agent with no checkpoints can be safer than a broadly scoped agent with checkpoints on only the obvious destructive actions, because scoping closes off entire classes of action rather than relying on catching every risky one at approval time.
Deployment shape changes what sessions and checkpoints mean in practice.
Running the bundled CLI binary locally keeps everything, including checkpoint approvals, on one machine with a human at the keyboard; a hosted execution model usually needs checkpoint approvals routed through some other channel (a queue, a webhook, a dashboard) since there's no terminal to prompt.
| Approach | Strength | Weakness | Best Fit |
|---|---|---|---|
| Single agent, built-in tools only | Simple to reason about and debug | No parallelism, one context window for everything | Small, self-contained tasks |
| Single agent + MCP servers | Extends reach without custom tool code | Adds an external dependency and its own failure modes | Tasks needing systems the SDK doesn't cover natively |
| Parent + subagents | Parallelizes independent work, isolates context | More moving parts, harder to trace end to end | Large tasks that split into clear independent pieces |
| Any of the above + checkpoints | Adds a human veto before irreversible actions | Adds latency and an operational dependency on a reviewer | Anything touching production data, money, or deletion |
Common Misconceptions
- "query() just sends one prompt and gets one response." It starts a loop; the response you get back is the result after the model has potentially called tools, observed results, and decided again, possibly many times.
- "Enabling a built-in tool means the agent can do anything with it." Tool access can be scoped down to specific allowed tools and paths; enabling "file edit" does not have to mean unrestricted filesystem access.
- "Subagents are just a way to save tokens." Context isolation is the primary benefit; the ability to run independent subagents in parallel and keep their intermediate reasoning from crowding the parent's context matters as much as any token savings.
- "Sessions and checkpoints are the same safety mechanism." Sessions are about continuity of context across runs; checkpoints are about pausing for approval before a specific action. Neither substitutes for the other.
- "MCP is only for connecting to remote APIs." MCP servers can run locally over stdio just as easily as over HTTP; the protocol doesn't care whether the tool lives on your machine or across the network.
FAQs
Is the Claude Agent SDK the same thing as Claude Code?
- No, but they share the same underlying primitives.
- Claude Code is a specific CLI product built on top of these primitives, aimed at software engineering.
- The Agent SDK exposes those primitives directly so you can build an agent for any domain, not just coding.
What actually happens when I call query()?
It starts a tool-use loop: the model reasons about your request, optionally calls one or more tools, observes each result, and repeats until it produces a final answer or a stopping condition (like a step limit) is reached.
Do I have to enable file edit, bash, and web tools every time?
No. Tool access is opt-in and scoped; you choose which built-in tools an agent can use for a given task, down to specific allowed operations, rather than granting everything by default.
When should I use a subagent instead of just adding another tool?
- When a subtask is genuinely independent and would otherwise crowd the parent's context with irrelevant intermediate steps.
- When you want to parallelize multiple independent workstreams.
- Not for every small helper action; a single well-scoped tool call is often simpler.
What is a human-in-the-loop checkpoint, mechanically?
It's a pause the SDK inserts right before a specific tool call executes, typically one marked destructive or irreversible, which blocks until a human approves or rejects it before the loop's "act" step proceeds.
Do sessions persist forever?
Sessions persist however long you choose to store the session identifier and its associated history; the SDK gives you the mechanism to resume, but retention and storage are your application's responsibility.
How is MCP different from a built-in tool?
Built-in tools (file edit, bash, web) ship with the SDK itself. MCP tools live on a separate server, local or remote, that you register; once registered, the loop calls them the same way it calls built-in tools.
Can a subagent use different tools than its parent?
Yes. Each subagent has its own tool scope, which is one of the main reasons to use one: you can hand a subagent only what it needs for its specific piece of the task.
What stops the tool-use loop from running forever?
The loop ends when the model produces a final answer instead of another tool call, or when a configured stopping condition (such as a maximum number of turns) is reached.
Does adding more tools make an agent smarter?
Not directly. More tools widen what the agent can act on, but the model still has to correctly decide when each tool applies; unscoped, excessive tool access mainly widens the blast radius of a wrong decision.
Is Python or TypeScript the "real" SDK?
Both are first-class packages for the same underlying SDK. This section defaults to Python for its examples, but the same concepts, loop, tools, subagents, and sessions, apply in TypeScript.
Related
- Claude Agent SDK Basics - install the package and run your first query()
- Enabling File Edit, Bash, and Web Tools in the Agent SDK - scoping built-in tools in practice
- Delegating Work to Subagents in the Claude Agent SDK - the isolation model in more depth
- Adding Human-in-the-Loop Checkpoints to an Agent SDK Workflow - pausing the loop before irreversible actions
- Persisting Sessions Across Runs with the Claude Agent SDK - resuming context across process runs
- Connecting the Claude Agent SDK to MCP Servers - widening the loop's reach with external tools
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the Claude Agent SDK (latest release, Python and TypeScript). Model names, SDK versions, and pricing move quickly - verify current specifics at platform.claude.com/docs before relying on them.