{"post":{"slug":"claude-agent-sdk-explained-2026","title":"What the Claude Agent SDK Enables for Developers","excerpt":"The Claude Agent SDK packages Claude Code itself into a library you can embed in your own product. Here's what it actually gives you, how it differs from the Tool Runner and Managed Agents, and when to reach for it.","category":"ai","date":"July 31, 2026","author":"ByteLedger Team","content":"<span class=\"dropcap\">T</span>he 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.\n\n## How it works\n\nYou 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.\n\nBeyond 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.\n\n## Where it sits among your options\n\nAnthropic 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:\n\n| Approach | You write | Who hosts it | Built-in tools |\n| --- | --- | --- | --- |\n| Manual loop | The entire request/response loop yourself | You | None — only what you define |\n| Tool Runner | Just your tool functions | You | None — only what you define |\n| Claude Agent SDK | A prompt plus options | You | Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch |\n| Managed Agents | Agent config plus tool results | Anthropic | Anthropic-hosted sandbox: bash, files, code execution |\n\nThe 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.\n\n## When to actually reach for it\n\nThe 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.\n\n## Common mistakes\n\n- **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.\n- **Expecting Anthropic to host it.** The Agent SDK supplies the harness, not the deployment — you still need to run it somewhere, unlike Managed Agents.\n- **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.\n- **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.\n\n## FAQ\n\n**Is the Claude Agent SDK the same thing as Claude Code?**\nIt'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.\n\n**Do I need the Managed Agents API to use the Agent SDK?**\nNo, 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.\n\n**Which model should I run it with?**\nAny 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.\n\n**Can I add my own custom tools alongside the built-in ones?**\nYes, and you can also connect external MCP servers, which is the same mechanism Claude Code itself uses to reach outside its built-in toolset.\n\n## Where to go next\n\nFor a workload-specific breakdown of which model to run underneath an agent like this, see [the best Claude 5 model for coding](/blog/best-claude-5-model-for-coding-2026). If you're comparing this to more visual, GUI-driving agents, read [how computer-use AI agents work and where they fail](/blog/ai-computer-use-agents-explained-2026), or see an editor-based alternative in [how to use the Cursor AI editor](/blog/how-to-use-cursor-ai-editor-2026).","hue":219,"metaTitle":"Claude Agent SDK Explained for Developers 2026","metaDescription":"What the Claude Agent SDK is, what it ships out of the box, and how it differs from the Tool Runner and Managed Agents in the Claude API.","keywords":["claude agent sdk","claude agent sdk explained","claude agent sdk vs tool runner","claude agent sdk vs managed agents","build ai agent with claude","claude code sdk","anthropic agent sdk","claude 5 model family"],"tldr":["**It is Claude Code packaged as a library** — the same agent loop and built-in tools that power the Claude Code CLI, embeddable in your own application.","**It ships built-in tools out of the box** — file read/write/edit, bash, grep, web search, and web fetch, without you writing tool definitions yourself.","**You still host and deploy it** — the SDK supplies the harness, not the infrastructure; that split is what separates it from Managed Agents.","**It is not the same thing as the Tool Runner** — the Tool Runner loops only over tools you define with no built-in filesystem access; the Agent SDK is the full Claude Code harness.","**Skip:** reaching for the Agent SDK when you just need a simple agentic loop over one or two custom tools — the Tool Runner is the lighter, more appropriate option there."],"readTime":"4 min read","wordCount":954},"related":[{"slug":"ai-agents-tutorial-2026","title":"AI agents tutorial in 2026: build your first agent in 30 minutes","excerpt":"Build a working AI agent in 2026 with the minimum viable stack — one model call, two tools, and a loop. Plus the patterns that separate toy agents from useful ones.","category":"ai","date":"February 12, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":200},{"slug":"claude-fable-5-explained-2026","title":"What Claude Fable 5 Is and How It Differs From Opus 5","excerpt":"Claude Fable 5 is Anthropic's most capable widely released model, priced above Opus 5 for the hardest reasoning and longest agentic runs. Here's what makes it different, and who actually needs it.","category":"ai","date":"July 29, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":201},{"slug":"claude-opus-5-review-2026","title":"Claude Opus 5 Review: What It Is Built For vs Sonnet 5","excerpt":"Claude Opus 5 keeps Opus 4.8's $5/$25 pricing while turning thinking on by default and adding a faster mode. Here's what it's actually for, and when Sonnet 5 already does the job.","category":"ai","date":"July 29, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":198}],"sameCategory":[{"slug":"agent-cost-attribution-2026","title":"Agent Cost Attribution: Finding Where the Tokens Went","excerpt":"A single monthly API bill tells you that agents are expensive. It does not tell you which feature, which customer, or which retry loop is responsible. That gap is fixable.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":220},{"slug":"human-in-the-loop-agents-2026","title":"Human-in-the-Loop Agents: Where to Put the Approval Gate","excerpt":"Approve everything and the agent is a slow autocomplete. Approve nothing and you have handed irreversible actions to a system that can be talked into things.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":197},{"slug":"reasoning-effort-controls-2026","title":"Reasoning Effort Controls: Tuning How Hard a Model Thinks","excerpt":"Fixed thinking budgets gave way to effort levels, and the default is rarely the right setting. Here is how the dial behaves and where each level actually belongs.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":210},{"slug":"retrieval-metrics-explained-2026","title":"Retrieval Metrics: Measuring the Half of RAG That Fails","excerpt":"When a RAG system answers badly, the retrieval usually failed before the model ever spoke. Measuring generation quality alone hides that entirely.","category":"ai","date":"August 19, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":215}],"newer":{"slug":"circuit-breaker-pattern-explained-2026","title":"Circuit Breaker Pattern Explained in 2026","excerpt":"A circuit breaker stops calling a dependency once failures cross a threshold, protecting the rest of the system from cascading timeouts. Here is how its three states actually work.","category":"code","date":"July 31, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":320},"older":{"slug":"claude-code-vs-windsurf-2026","title":"Claude Code vs Windsurf in 2026: Which Agent Fits You","excerpt":"Claude Code and Windsurf both write and edit real code across your project, but they start from opposite ends: a terminal-first agent versus a full AI native editor. Here is how they actually differ in daily use.","category":"ai","date":"July 31, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":206}}