The Claude Agent SDK Mental Model
The Claude Agent SDK is Anthropic's library for building production AI agents in Python or TypeScript.
//
Search across all documentation pages
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.
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.
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.
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 |
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Reviewed by Chris St. John·Last updated Jul 16, 2026