The Claude Agent SDK takes Claude Code — the coding agent Anthropic ships as a CLI — and packages it as a library you can embed directly in your own application. That distinction matters: it isn't a thin wrapper for calling the API with your own tools, and it isn't a hosted service that runs somewhere else. It's the actual agent loop, built-in tools, and context management that make Claude Code work, available to call from your own code, on your own infrastructure.
How it works
You call a single function — query — with a prompt and an options object, and the SDK handles the rest: it runs the agent loop, decides when to use tools, manages context as the conversation grows, and returns results. Out of the box, it ships with the same built-in tools Claude Code uses directly: reading, writing, and editing files; running bash commands; searching with glob and grep; and fetching or searching the web. You don't write JSON schemas for any of these — they're already there, tuned and tested as part of the product.
Beyond the built-in toolset, the SDK also exposes the machinery around the loop: hooks for intercepting or modifying behavior at specific points, subagents for delegating scoped pieces of work, a permissions system for gating what the agent can do, and sessions for maintaining state across a longer interaction. It also supports MCP, so you can connect it to external tool servers the same way Claude Code itself does.
Where it sits among your options
Anthropic actually offers four distinct ways to build an agent on top of Claude, and mixing them up leads to the wrong tool for the job:
| Approach |
You write |
Who hosts it |
Built-in tools |
| Manual loop |
The entire request/response loop yourself |
You |
None — only what you define |
| Tool Runner |
Just your tool functions |
You |
None — only what you define |
| Claude Agent SDK |
A prompt plus options |
You |
Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch |
| Managed Agents |
Agent config plus tool results |
Anthropic |
Anthropic-hosted sandbox: bash, files, code execution |
The Tool Runner and the Claude Agent SDK are easy to conflate because both are "harness only" — you still host and deploy the compute either way. The difference is scope: the Tool Runner is a thin helper over the Messages API that loops over tools you define, with no filesystem access or built-in capabilities of its own. The Agent SDK is the full Claude Code harness, complete with a working toolset already built in. Managed Agents is the only option where Anthropic runs both the loop and the sandbox where tools execute — that's the right choice when you want to hand off infrastructure entirely, not just tool logic.
When to actually reach for it
The Claude Agent SDK earns its place when you want a batteries-included, coding- or filesystem-oriented agent running on infrastructure you control — an internal dev tool, a code review bot, a documentation generator, or any product where "read files, run commands, edit code" is close to the actual job description. If your agent only ever needs one or two custom tools and no filesystem access, the Tool Runner is lighter and avoids pulling in a toolset you won't use. If you'd rather not run any infrastructure at all — no server, no container to manage — Managed Agents is the more appropriate starting point.
Common mistakes
- Treating the Agent SDK and the Tool Runner as interchangeable. They solve different problems: one hands you Claude Code's built-in tools and loop, the other hands you a loop over tools you write yourself.
- Expecting Anthropic to host it. The Agent SDK supplies the harness, not the deployment — you still need to run it somewhere, unlike Managed Agents.
- Reaching for it for a narrow, single-purpose agent. If the job is calling one API and returning a result, a manual loop or the Tool Runner is simpler and has less surface area to reason about.
- Ignoring the permissions system. Built-in bash and file-editing tools are powerful by default — configure what the agent is actually allowed to do rather than running it wide open.
FAQ
Is the Claude Agent SDK the same thing as Claude Code?
It's the same underlying harness and tools, packaged as a library instead of a CLI, so you can embed it in your own product rather than running it as a standalone terminal tool.
Do I need the Managed Agents API to use the Agent SDK?
No, they're separate. The Agent SDK is harness-only and runs on your own infrastructure; Managed Agents is a different surface where Anthropic hosts both the loop and the sandbox.
Which model should I run it with?
Any current Claude model works, but for coding- and filesystem-heavy tasks the Sonnet 5 and Opus 5 tiers are the common choices — see our coding-specific model guide for the tradeoffs.
Can I add my own custom tools alongside the built-in ones?
Yes, and you can also connect external MCP servers, which is the same mechanism Claude Code itself uses to reach outside its built-in toolset.
Where to go next
For a workload-specific breakdown of which model to run underneath an agent like this, see the best Claude 5 model for coding. If you're comparing this to more visual, GUI-driving agents, read how computer-use AI agents work and where they fail, or see an editor-based alternative in how to use the Cursor AI editor.