Ask a dozen engineering teams what slowed down their first AI agent and you hear the same answer: not the model, the plumbing. The tool-execution loop. The context window that quietly overflows hours into a long task. The permission layer that either nags constantly or approves what it should not. Anthropic hit all of it building Claude Code, then shipped the fix as a library.
| Quick answer: The Claude Agent SDK is Anthropic’s official Python and TypeScript library for building AI agents on the same agent loop, built-in tools and context management that power Claude Code. You supply a prompt and options; the SDK runs the loop while Claude decides which tools to call and when the task is finished. |
Disclosure: TechieHub is reader-supported. Some outbound links are affiliate links that may earn us a commission at no extra cost to you. Assessments are made independently and are never paid placements.
Table of Contents
What is the Claude Agent SDK?
The Claude Agent SDK is a software library published by Anthropic that exposes the agent harness behind Claude Code as programmable code in Python and TypeScript. An agent here is an application that plans its own steps and calls tools that read files, run shell commands, search the web or edit code. The SDK supplies the harness — loop, tools, context management, permissions — and leaves the business logic to you.
It did not start under this name. The package launched as the Claude Code SDK and was renamed in September 2025, because developers had outgrown the label — they were shipping research assistants, support bots and document reviewers on it. The rename brought real package changes: claude-code-sdk became claude-agent-sdk on PyPI, @anthropic-ai/claude-code became @anthropic-ai/claude-agent-sdk on npm, and ClaudeCodeOptions became ClaudeAgentOptions. If an older tutorial’s imports fail, that is usually why.
Two constraints matter before you commit. First-party support covers Python and TypeScript only; to drive the same loop from Go or Rust, you run the Claude Code CLI as a subprocess with the -p flag and --output-format json. And the SDK is Claude-native — you commit to Anthropic’s models, a different trade from the framework-first approach in our guide to building an AI agent from scratch.
How does the Agent SDK actually work?
The entry point is a single function, query(), which takes a prompt plus an options object and returns an async iterator. Each turn of the loop yields a message — Claude’s reasoning, a tool call, a tool result, or the final outcome — while the SDK handles orchestration, tool execution, context management and retries. The loop ends when Claude decides the task is complete or hits an error.
Control comes from the options object, not from code you write. allowedTools pre-approves specific tools; permissionMode sets the oversight posture. Six modes exist, and choosing between them is the most consequential decision in an SDK project: default routes every request through your approval callback, plan keeps the agent read-only while it scopes work, acceptEdits auto-approves file changes, dontAsk denies anything outside your allow-list, auto hands approval to a model classifier, and bypassPermissions runs everything unprompted for sandboxed CI.
The shortest working agent
Assembled, the pieces above are smaller than most people expect. This is a complete read-only agent — it can inspect a repository and report back, but cannot change anything:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find every TODO comment and summarise them by file.",
options: {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "plan", // read-only: nothing can be modified
cwd: "/path/to/repo",
},
})) {
if (message.type === "result") console.log(message.result);
}Two details carry most of the safety. allowedTools is an allow-list, so anything absent from it — Write, Edit, Bash — simply is not available to the model. And permissionMode: "plan" keeps the agent read-only regardless of what it decides to attempt. Widening either one is a deliberate act, which is exactly the property you want when the agent runs unattended.
Delegation is where the harness earns its keep, and Anthropic has published numbers on it. In the engineering write-up of its own multi-agent Research system, an orchestrator coordinating subagents outperformed a single agent by 90.2% on internal evaluations, while consuming roughly 15 times the tokens of a normal chat exchange. That ratio is the honest framing: the architecture wins when the task is worth the token bill, and not before.
What do you get out of the box?
The built-in toolset is what most teams underestimate. Read, Write, Edit, Bash, Glob, Grep, WebSearch and WebFetch ship enabled, so an agent can inspect a repository, run a test suite, search the web and patch a file without you writing a single tool handler.
Around those tools sit four building blocks. Hooks run your code at defined points in the agent lifecycle — how you add logging, redaction or a hard stop before a destructive command. Subagents spawn specialised children with their own context windows. Sessions persist context across exchanges so a run can be resumed or forked. Plugins bundle skills, agents, hooks and MCP servers. Skills, slash commands and memory load automatically from .claude/ and ~/.claude/, exactly as in Claude Code.
The block with the widest reach is protocol support. The Claude Agent SDK has first-class support for the Model Context Protocol, the open standard Anthropic released for connecting models to external tools and data. Rather than hand-rolling an integration for every database, browser or SaaS API, you point the agent at an MCP server and the tools appear — a pattern we unpack in our explainer on the Model Context Protocol and why it matters.
What does it cost to run an Agent SDK agent?
The library itself is free. You pay for the tokens your agent consumes — input, output and cache — at standard Claude API rates. Claude Opus 5 launched on 24 July 2026 at $5 per million input tokens and $25 per million output tokens and became the default model on Claude Max, so that is the price point most new agents budget against.
One widely repeated claim needs correcting, because guides published in spring 2026 still carry it. Anthropic announced that from 15 June 2026, Agent SDK and claude -p usage on subscription plans would move to a separate monthly credit with usage-based overages. That change was paused on the day it was due to take effect. Programmatic usage still draws from existing Pro, Max, Team and Enterprise limits. Treat any article stating otherwise as out of date.
There is a real licensing constraint to plan for instead. Without prior approval from Anthropic, you may not offer claude.ai login or claude.ai rate limits to your own users through a product built on the SDK. Production agents authenticate with an API key, or via Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform or Microsoft Foundry. Requirements are modest — Node.js 18+ or Python 3.10+ — and both packages bundle a native Claude Code binary.
Agent SDK, Claude Code or Managed Agents?
Anthropic ships four ways to put Claude to work, and picking the wrong one costs weeks. The distinction that matters is who runs the loop and who hosts the compute.
| Option | What it is | Best for |
| Claude Agent SDK | The Claude Code harness as a Python or TypeScript library | Custom production agents running in your own process |
| Claude Code CLI | The terminal and IDE product for interactive use | Day-to-day coding with a human in the loop |
| Client SDK (Claude API) | Direct model calls; you write the tool loop | Simple prompts and fully bespoke control flow |
| Managed Agents | Hosted REST API; Anthropic runs the loop and sandbox | Long-running async agents with no infra to manage |
| Model-agnostic frameworks | LangGraph, CrewAI and similar | Provider flexibility or graph-based state control |
How we compare: this table is built from the official Claude Agent SDK documentation and changelogs rather than vendor marketing, cross-checked against the public Python repository and dated coverage of the June 2026 billing reversal. Untraceable claims were left out. Read it alongside our roundups of the best AI coding tools available today and the strongest autonomous coding agents.
The coding heritage still shows in where the SDK turns up. In February 2026, Apple shipped Xcode 26.3 with native Claude Agent SDK integration — subagents, background tasks and plugins inside the IDE, plus visual verification that lets the agent screenshot a SwiftUI preview and iterate until it matches intent.
What does this look like on a real team?
Consider Rhiannon Vaughan, a platform engineer at a forty-person payments company — a representative composite of the workflow teams describe most often. Every morning she inherited the same chore: roughly thirty integration tests had failed overnight, most flaky, a few genuine regressions, and separating them ate the first ninety minutes of her day.
She wrote about eighty lines of TypeScript: a query() call with allowedTools set to Read, Glob, Grep and Bash, and permissionMode left at plan so nothing could be modified. The agent pulled the CI logs, re-ran each failing test three times to separate real failures from flakes, traced the genuine ones through git log to the offending commit, and posted a ranked summary to Slack via an MCP server.
The outcome was not that the agent fixed the bugs — it never had write access. It was that Rhiannon arrived to a triaged list with suspect commits already named, turning a ninety-minute chore into a ten-minute review. That is the shape of work the Claude Agent SDK suits: multi-step, tool-heavy, too structured for one model call and too messy to script by hand.
Frequently Asked Questions
Is the Claude Agent SDK the same thing as Claude Code?
They share one harness but serve different users. Claude Code is the finished product — a CLI and IDE tool for interactive work with a human approving each step. The Agent SDK is that same engine exposed as a library, giving developers programmatic control over routing, parallel execution and subagent lifecycle inside their own applications.
Which programming languages does the Agent SDK support?
Anthropic ships first-party packages for Python 3.10 or later and for TypeScript on Node.js 18 or later. The two share a conceptual model, with matching option classes and identical tool names. For any other language, run the bundled Claude Code CLI as a subprocess using the -p flag with --output-format json.
Do I need to install Claude Code separately?
No. Both the Python and TypeScript packages bundle a native Claude Code binary for your platform, so pip install claude-agent-sdk or npm install @anthropic-ai/claude-agent-sdk is the only install step. You then set an ANTHROPIC_API_KEY environment variable in the shell that runs your agent; the SDK does not read .env files automatically.
Did Agent SDK usage move to separate monthly credits in June 2026?
No. Anthropic announced a change for 15 June 2026 that would have shifted Agent SDK and headless usage onto separate monthly credits with usage-based overages, then paused it on the day it was due to launch. Programmatic usage still draws from existing Pro, Max, Team and Enterprise subscription limits.
Does the Agent SDK work with MCP servers?
Yes, and support is first-class rather than bolted on. You declare MCP servers in the options object and their tools become available to the agent alongside the built-in ones. Because Anthropic authored the Model Context Protocol, connecting databases, browsers, issue trackers and internal APIs needs no bespoke integration code.
When should I choose Managed Agents instead of the Agent SDK?
Choose Managed Agents when you want Anthropic to host both the agent loop and a per-session sandbox — useful for long-running asynchronous work with no infrastructure of your own. Choose the Agent SDK when the agent must run inside your process, touch your local filesystem, or use hooks and custom permission callbacks you control.
Conclusion
The Claude Agent SDK is a straightforward trade: you give up model portability and skip the months of agent plumbing Anthropic already paid for in production. The loop, context management, permission system and subagent coordination all arrive solved, so the code you write describes your actual problem. For teams already on Claude, that is one of the shortest routes from idea to a reliable agent — provided you set permission modes deliberately, verify pricing against official documentation rather than second-hand write-ups, and reserve the multi-agent pattern for tasks whose value justifies the tokens.
