Explainer
What Is the Claude Agent SDK?
The Claude Agent SDK is Anthropic's official toolkit for building autonomous AI agents on the exact harness that powers Claude Code — the agent loop, tool use, context management, MCP and subagents — shipped as a TypeScript package (@anthropic-ai/claude-agent-sdk) and a Python package (claude-agent-sdk). It was previously called the Claude Code SDK.
01 / Definition
The Claude Agent SDK lets you build your own AI agents that can read and edit files, run shell commands, search the web and call external tools — without re-implementing the agent loop yourself. Instead of making raw model calls and orchestrating tools by hand, you hand the SDK a prompt and a set of options, and it runs the same plan-act-observe loop that Claude Code uses in the terminal, streaming back messages, tool calls and a final result.
It is distributed for two runtimes: TypeScript/Node via the npm package @anthropic-ai/claude-agent-sdk (0.3.185, verified 2026-06-21) and Python via the PyPI package claude-agent-sdk (0.2.106, verified 2026-06-21). Both wrap the Claude Code agent harness, so an agent you build with the SDK inherits the same tools, permission model and MCP support as the CLI. The product was renamed from the "Claude Code SDK" in 2025 to reflect that it builds general-purpose agents, not only coding tools — see our Claude Code SDK note for the rename details.
02 / What it does
-
The same harness as Claude Code
Your agent runs on the identical agent loop, context management and tool execution that power the Claude Code CLI. You are not gluing together prompts and a tool router — the loop, retries, streaming and result handling are built in.
-
Tools and file system access out of the box
Agents can read, write and edit files, run bash commands, search the codebase and fetch from the web using the same built-in tools Claude Code ships with. You scope what they can touch with the permission system rather than wiring each tool up yourself.
-
MCP servers, subagents and permissions
Connect Model Context Protocol servers (GitHub, Figma, databases) to extend what the agent can do, spawn subagents for parallel or isolated work, and gate risky actions with allow / ask / deny permission rules — all configured through SDK options.
-
TypeScript and Python, bring your own model auth
Use query() in either language to start an agent. It authenticates with an ANTHROPIC_API_KEY or a Claude subscription login, and can also run against Claude on Amazon Bedrock or Google Vertex AI. The SDK is free; you pay only for the Claude model usage your agent incurs.
03 / How it works
At the core is a single entry point — query() in both the TypeScript and Python SDKs — that takes your prompt plus an options object (model, allowed tools, MCP servers, permission mode, working directory) and returns an async stream of messages: the agent's text, each tool call and result, and a final result message with usage. Under the hood the SDK drives the Claude Code agent harness, so the model plans, calls tools, observes the results and repeats until the task is done. Model access is configurable — point it at a current Claude model such as claude-opus-4-8 (most capable), claude-sonnet-4-6 (balanced) or claude-haiku-4-5 (fastest).
[screenshot: a terminal running a Python script that imports claude_agent_sdk, calls query(), and streams an agent editing files and printing a final result. Capture on a dark theme at 2x.]
The Anthropic API SDK (@anthropic-ai/sdk / anthropic) gives you raw Claude model calls that you orchestrate yourself. The Claude Agent SDK gives you the whole agent — loop, tools, file access, MCP and permissions — so you describe the task, not the plumbing.
04 / Who it's for
- Developers who want to build a custom coding or automation agent without re-implementing the agent loop, tool routing and context management.
- Teams already using Claude Code in the terminal who want to wrap the same capabilities into a script, service or CI job.
- Anyone who needs file-system, bash and MCP tool access driven by Claude, with permissions to keep it safe.
- Not the right fit if you only need a single model response — use the plain Anthropic API SDK for raw, one-shot Claude calls instead.
05 / Getting started
Install the SDK for your language (npm i @anthropic-ai/claude-agent-sdk or pip install claude-agent-sdk), set an ANTHROPIC_API_KEY, and call query() with a prompt. Our step-by-step tutorial walks through a first agent in both TypeScript and Python; if you only want the terminal tool, install Claude Code instead.
Our AI agents
From the team behind AI Coding Hub — agents that pick up where the code ends:
- AI document agentDraftlizeTurn rough notes, specs and transcripts into clean, structured docs with an AI doc agent.Try Draftlize →
- AI presentation agentDecklizeGenerate editable slide decks from a prompt or an existing doc with an AI presentation agent.Try Decklize →
- AI data agentTablizeQuery, clean and chart spreadsheets and CSVs in plain English with an AI data agent.Try Tablize →
FAQ
- Is the Claude Agent SDK the same as the Claude Code SDK?
- Yes. The Claude Agent SDK is the renamed Claude Code SDK — same product, new name (and new package names) since 2025. If a tutorial references the "Claude Code SDK", it is talking about today's Claude Agent SDK.
- What languages does the Claude Agent SDK support?
- Two officially: TypeScript/JavaScript via the npm package @anthropic-ai/claude-agent-sdk, and Python via the PyPI package claude-agent-sdk. Both expose a query() entry point and the same agent capabilities.
- Do I need an API key to use it?
- You need Claude model access. That can be an ANTHROPIC_API_KEY from the Anthropic Console, or a Claude Pro/Max/Team subscription login. The SDK can also run against Claude on Amazon Bedrock or Google Vertex AI. The SDK itself is free — you pay for model usage.
- How is the Claude Agent SDK different from the Anthropic API SDK?
- The Anthropic API SDK (@anthropic-ai/sdk or anthropic) is a thin client for raw Messages API calls — you write the agent loop and tool handling. The Claude Agent SDK is a full agent framework: it runs the loop, executes built-in tools (file edits, bash, web), supports MCP and subagents, and enforces permissions. Use the API SDK for one-shot calls; use the Agent SDK to build an agent.
- Which model should I use with it?
- Any current Claude model. For agentic coding, claude-opus-4-8 is the most capable; claude-sonnet-4-6 balances speed and cost; claude-haiku-4-5 is the fastest and cheapest for simple tasks. You set the model in the SDK options.