Home › Claude Ecosystem Guides

The Claude Agent SDK, explained

The Claude Agent SDK is Claude Code packaged as a library: you hand it a prompt and options, and it drives the entire agent loop with built-in tools running on your own infrastructure.

Last reviewed: 2026-09-04 · Українською

A library, not just an API call

The plain Messages API gives you a single request-and-response. To turn that into an agent, you normally write a while loop yourself: send the prompt, receive tool_use blocks, run them, feed back tool_result blocks, repeat until the model stops. The Claude Agent SDK is a separate product that hands you that whole machine assembled. It is the engine behind Claude Code, exposed as a library you embed in your own program.

You call it with a prompt plus options, and it owns the loop end to end: deciding when to call a tool, executing it, threading results back, and knowing when the task is finished. Your job shrinks to describing the goal and configuring guardrails, not orchestrating the conversation turn by turn.

Batteries included: built-in tools and context

The SDK's defining feature is that it ships with a working toolset. Out of the box it can read, write, and edit files, run shell commands, search a codebase, and fetch from the web — the same capabilities that make Claude Code useful at the terminal. You do not define these tools; they are already wired in.

On top of the tools, it manages the things a real agent needs to run for many steps without falling apart:

• Context management, so a long session does not overflow the window.
• Permissions and hooks, so you can gate or observe risky actions.
• Subagents and sessions for structuring larger jobs.
• MCP support, so it can also reach external tools and data through that protocol.

How it compares to the alternatives

Four ways of building on Claude sit on a spectrum of how much you write versus how much is handed to you. Knowing where the Agent SDK falls is the whole decision.

• Plain Messages API loop — you write the while-loop and define every tool. Maximum control, maximum boilerplate.
• SDK Tool Runner — loops over tools you define, but with no built-in tools. It automates the loop, not the capabilities.
• Claude Agent SDK — the loop and a full built-in toolset, running on your infrastructure.
• Managed Agents — Anthropic hosts the loop and a sandbox for you; you give up infrastructure control for convenience.

The Agent SDK is the point where you get a coding-and-filesystem agent for free but still run it yourself.

When to reach for the Agent SDK

Choose it when you want a capable filesystem or coding agent and you want it on your own servers, your own network, your own file paths. If your task is "read this repository, make a change across several files, run the tests, and report back," the SDK already knows how to do all of that — you are not going to out-build its file and shell tools by hand.

Reach for the plain API loop instead when your agent's tools are entirely bespoke and you want tight control over each turn. Reach for Managed Agents when you would rather not operate any infrastructure at all. The Agent SDK is the middle path: batteries included, but yours to host.

A concrete picture

Imagine a triage bot that watches a bug report, opens the relevant repository, greps for the failing function, edits the fix, runs the test suite, and posts a summary. With the plain API you would define a file-read tool, a file-write tool, a grep tool, a bash tool, and hand-write the loop that sequences them. With the Agent SDK you supply the prompt and let its built-in tools do the reading, editing, searching, and running, while hooks let you require approval before anything is committed.

Everything an agent does still rests on tool use as its foundation; the SDK simply saves you from rebuilding that foundation, plus the loop, plus a default toolset, every time.

Frequently asked

Is the Claude Agent SDK the same as the Claude API?

No. The API gives you a single message request-and-response, and you build the agent loop yourself. The Agent SDK is a separate product — Claude Code as a library — that drives the loop and ships with built-in tools.

Do I still need to define my own tools with the Agent SDK?

Not for the common ones — file read/write/edit, shell, code search, and web fetch are built in. You can add your own tools, including external ones over MCP, when your task needs capabilities beyond the defaults.

When should I use Managed Agents instead of the Agent SDK?

Use Managed Agents when you would rather Anthropic host both the loop and a sandbox. Use the Agent SDK when you want that same batteries-included agent running on your own infrastructure and file system.

Continue in this track