The Claude Agent SDK
Low-competition territory: named in job ads, rarely understood. The one-line answer is Claude Code packaged as a library — the same harness, the same built-in tools, called from your own code instead of a terminal.
The four ways to build an agent
This is the part worth memorising, because the names collide badly. Two questions separate them: who supplies the harness (the loop and context management) and who supplies the deployment.
| Approach | Harness | Deployment |
|---|---|---|
| Manual loop | you | you |
| Tool Runner | SDK | you |
| Claude Agent SDK | SDK, with built-in tools | you |
| Managed Agents | Anthropic | Anthropic |
Tool Runner and Agent SDK are different packages, and confusing them is the common error. The Tool Runner lives inside the ordinary API SDK and loops over tools you define — no built-in tools, no filesystem, no sandbox. The Agent SDK ships the whole Claude Code harness: file read/write/edit, bash, glob, grep, web search and fetch, plus context management, hooks, permissions, sessions and subagents.
Only Managed Agents adds hosting. The Agent SDK is harness-only — you still deploy it, which is the fact people miss when they assume it is a service.
What you actually write
from claude_agent_sdk import query
async for message in query(
prompt="Fix the failing test in tests/test_auth.py",
options=...,
):
print(message)A prompt and options. The SDK drives the loop, decides which built-in tools to call, manages the context window, and streams messages back. That is the appeal and the trade: you get a capable coding agent immediately, and you give up control of the loop.
The pieces worth naming
Built-in tools
Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch. This is the difference from every other option — with the Tool Runner or a manual loop you supply all of that yourself.
The consequence is a security one: an agent that can run bash and edit files needs a sandbox and a permission model, which is why those are first-class features rather than extras. See Computer-use and code agents.
Subagents
A subagent runs a sub-task in its own context window and reports back. The property that matters: it does not inherit the parent’s conversation, so the parent must restate every fact the child needs.
That is the whole design constraint. A subagent brief that assumes shared context produces a confidently wrong result, and the fix is a complete, self-contained task description plus an explicit output contract for what the child returns.
The reason to use one is context isolation, not parallelism alone: a research or file-reading task that would fill the parent’s window runs in a child’s instead, and only the summary comes back.
Skills
A skill is a folder with a SKILL.md carrying frontmatter — a name, a
description, and instructions the agent loads when the description matches the
task. That is progressive disclosure: the description sits in context always,
the body only when relevant.
Skills can restrict which tools they permit and can fork context. The framing for an interview: a skill is a lazily-loaded prompt with a trigger condition, which is how you scale instructions past what fits in one system prompt.
The whole file is frontmatter plus prose:
---
name: release-notes
description: Write release notes from merged PRs.
Use when the user asks to draft a changelog.
allowed-tools: Read, Grep
---
Group changes by user impact, not by author...The failure mode is the description. It is the trigger, so a vague one never
fires and an over-eager one fires constantly. description is loaded always;
the body only when it matches — that asymmetry is the entire design.
MCP and permissions
MCP servers plug in as extra tools alongside the built-ins — the same servers you would write for any other client, which is the point of the protocol. See Building an MCP server, end to end.
Hooks intercept tool calls, which is where approval gates, logging and policy live. This is the mechanism that makes an autonomous agent auditable, and it is the honest answer to “how do you control what it does” — in code at the boundary, not by asking the model nicely.
When it is the right choice
| Situation | Reach for |
|---|---|
| Coding agent, own infra | Agent SDK |
| Only your own tools | Tool Runner |
| Sandbox hosted too | Managed Agents |
| Cross-provider portability | LangGraph, etc. |
The deciding question is whether you want the built-in tools. If the task is “operate on a repository”, the Agent SDK saves you writing and securing eight tools. If the task is “call our three internal APIs”, those built-ins are attack surface you did not need.
Gotcha: it is provider-specific by design. That is a real lock-in decision, and the counterweight is that the harness is the part you would otherwise spend months getting right — see The agent framework landscape for the portability argument.
Related
Interview angle 6
- “What is the Claude Agent SDK?” - Claude Code packaged as a library: the same harness and built-in tools — read, write, edit, bash, glob, grep, web search — called from your code. You supply a prompt and options; it drives the loop, context management and tool selection.
- “How is it different from the Tool Runner?” - different packages. The Tool Runner is part of the ordinary API SDK and loops over tools you define, with no built-in tools and no filesystem. The Agent SDK brings the full harness with built-ins. Both leave hosting to you; only Managed Agents adds that.
- “What’s the catch with subagents?” - a subagent does not inherit the parent’s conversation, so the brief has to be self-contained and specify what to return. The reason to use one is context isolation — heavy reading happens in a child’s window and only the summary comes back.
- “What is a skill?” - a folder with a SKILL.md whose description is the trigger and whose body loads only when the task matches. Progressive disclosure: it is how you scale instructions past one system prompt. A vague description never fires; an over-eager one always does.
- “How do you control what it does?” - hooks intercepting tool calls, plus the permission model and a sandbox. Policy belongs in code at the boundary, not in prompt instructions, because an agent with bash and file write is a privilege decision.
- “When would you not use it?” - when you only need your own tools, since the built-ins become attack surface you did not need, or when cross-provider portability matters — it is deliberately provider-specific.