The Claude Agent SDK Is Claude Code With the Terminal Removed
Anthropic's Claude Agent SDK lets a Python or TypeScript program run the same agent loop that powers Claude Code, with the same tools, hooks and subagents. Here is what it is, the twenty-line first agent, and the three limits to set before anyone else runs it.

Key takeaways
- The Claude Agent SDK is a Python and TypeScript library that runs the same agent loop, built-in tools, hooks, subagents and permissions as Claude Code, and it needs Python 3.10+ or Node.js 18.14+.
- The SDK was renamed from the Claude Code SDK, and v0.1.0 made two breaking changes: the Python type ClaudeCodeOptions became ClaudeAgentOptions, and Claude Code's system prompt stopped being the default.
- allowedTools only pre-approves the tools it lists, so the agent can still call other tools under your permission mode; the tools option is what limits the built-in set.
- A run ends on one of five result subtypes, and maxTurns and maxBudgetUsd are the two caps that stop it; neither is set by default, and a budget cap can be passed by the cost of one response.
- Subagents default to a maximum nesting depth of 3 layers and 20 running at once, and their spend counts toward the parent query's budget cap.
The Claude Agent SDK is Anthropic's library for running Claude Code's agent loop inside your own Python or TypeScript program.[1] You hand it a prompt and a list of tools, and it reads files, runs commands and edits code until the job is done, then returns the result with the cost attached.[3]
Claude Code is Anthropic's coding agent, the one that lives in your terminal. The SDK is that same engine with the terminal taken away, so your own program is the one holding the steering wheel.
It was called the Claude Code SDK until Anthropic renamed it, and the docs say the new name reflects broader uses “beyond coding tasks.”[5] Everything below was checked against Anthropic's docs on November 18, 2026, and the SDK moves fast, so treat version details as a snapshot.
What the SDK does with your call
You supply the prompt and the rules. The loop does the work.
What you pass in
- A promptThe task, in plain language
- Tools and permissionsWhich tools run unprompted, which are blocked
- LimitsMax turns, max budget, effort
The agent loop
Claude plans, calls a tool, reads the result, repeats
What streams back
- Messages as it worksReasoning, tool calls, tool results
- A final resultText, token usage, cost, session ID
- Changed filesWhatever the tools edited on disk
The loop ends when Claude answers without asking for another tool, or when a limit you set stops it.
It's Claude Code, minus the interface
Anthropic's own description is blunt: the SDK “gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.”[1] It runs the Claude Code binary underneath, so the built-in tools, permissions, sessions, hooks, subagents and Model Context Protocol (MCP) connections come along.[1]
“The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.”
That sentence is the whole pitch, and it explains why the SDK feels different from the usual agent tutorial. Most of those tutorials have you write the tool-calling loop yourself.
Here the loop already exists, along with the file and shell tools Claude Code ships with. If you want the background on MCP, our Claude MCP explainer covers it, and the general MCP primer goes deeper on the protocol itself.
Anthropic offers four ways to put Claude to work, and picking the wrong one is the most common early mistake.
| Option | Who runs the agent | You get |
|---|---|---|
| Agent SDK | Your process, in Python or TypeScript | Claude Code's tools, permissions, sessions and hooks as a library |
| Claude Code CLI | You, in a terminal | The interactive tool for daily use and one-off tasks |
| Client SDK | Your code, calling the API | Raw API access; you write the tool loop yourself |
| Managed Agents | Anthropic, in a hosted sandbox | A hosted harness configured through the Claude API |
Source: Anthropic, Agent SDK overview, checked November 18, 2026.
Takeaway
The question that sorts these four is who runs the loop. If you want to write it, use the Client SDK. If you want to rent it and keep it in your own process, use the Agent SDK. If you want Anthropic to host it, use Managed Agents.
The first agent is short because the loop is not your problem
Install it with pip install claude-agent-sdk or npm install @anthropic-ai/claude-agent-sdk. You need Python 3.10+ or Node.js 18.14+, and both packages bundle a native Claude Code binary, so most installs need nothing else.[2] Set ANTHROPIC_API_KEY in the shell that runs the script. The SDK does not read .env files, which will cost somebody an afternoon this week.[2]
Here is Anthropic's quickstart agent, which finds and fixes crash bugs in a file called utils.py.[2]
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"], # auto-approve these tools
permission_mode="acceptEdits", # auto-approve file edits
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text) # Claude's reasoning
elif hasattr(block, "name"):
print(f"Tool: {block.name}") # a tool being called
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}")
asyncio.run(main())Three things are happening. query() opens the loop and returns a stream. allowed_tools pre-approves three tools. permission_mode auto-approves file edits.[2] The agent then reads the file, spots the division by zero and the missing null check, and edits both, without you writing a single line of tool-handling code.
The loop is a cycle. Claude receives the prompt, decides what to do, and asks for tool calls. The SDK runs them, feeds the results back, and repeats until Claude replies without requesting another tool.
Anthropic's own example, “fix the failing tests in auth.ts,” takes four turns: run the tests, read two files, edit and re-run, then a text-only answer.[3] Each pass yields messages you can print, log or ignore.
allowedTools approves tools. It does not fence them in.
This is the detail I did not expect. Listing a tool in allowedTools means Claude may use it without asking. It does not mean Claude may use only those tools.
Tools you leave off the list are still available, and a call to one of them falls through to your permission mode.[3] To actually restrict the built-in set, you pass it as tools instead.[2]
If you read the option name as a whitelist, you will ship an agent that can run shell commands you never meant to allow. Anthropic documents the distinction, but the name does not help you.
| Permission mode | What happens to tool calls | Use it for |
|---|---|---|
| default | Unapproved calls go to your canUseTool callback; no callback means deny | Interactive apps with an approval prompt |
| acceptEdits | File edits and common filesystem commands are auto-approved | Prototyping in an isolated directory |
| plan | Claude explores and plans; edits go to your callback | Code review or a large change |
| dontAsk | Pre-approved tools run; everything that would prompt is denied | Headless agents with nobody to approve |
| bypassPermissions | Runs tool calls without asking, including unlisted tools | CI and containers only |
Source: Anthropic, How the agent loop works. The docs also list an auto mode that uses a classifier to review risky actions.
Heads up
bypassPermissions can't be used when the process runs as root on Unix, and the TypeScript SDK also demands allowDangerouslySkipPermissions: true. Anthropic says to reserve it for isolated environments where the agent's actions can't touch anything you care about.[3] Our agent sandbox guide covers what that isolation has to look like.There is a second control worth knowing about. Hooks are callbacks that fire before a tool runs, after it returns, when the agent stops, and at a few other points. A PreToolUse hook can reject a call, and Claude receives the rejection as the tool result.
Hooks run in your application process, so they don't spend any of the agent's context window.[3] For anything you would hate to see in a postmortem, a hook that blocks the command beats a sentence in the prompt asking nicely.
Subagents keep the main context clean, and multiply your bill
A subagent is a separate agent instance your main agent can spawn for a focused subtask. It runs in its own fresh conversation, and only its final message returns to the parent, so a research subagent can read dozens of files without any of that text piling up in the main context.[4]
Several can run at once, and each can have its own system prompt, tool list and model.[4]
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
prompt="You are a code review specialist...",
tools=["Read", "Grep", "Glob"], # read-only
model="sonnet",
),
},
max_turns=30,
max_budget_usd=5.0,
)The model field accepts the aliases fable, opus, sonnet, haiku or inherit, or a full model ID.[4] On the Anthropic API those aliases currently resolve to Claude Opus 5.5, Sonnet 5.5 and Haiku 5.5.[6] Which alias to give which subagent is a real cost decision, and our Opus versus Sonnet breakdown has the prices and the benchmark gaps.
Here is the catch. Claude decides when to spawn and how many, and a subagent can spawn its own. By default the SDK allows 3 layers of subagents below your main agent and 20 running at once, and every subagent request counts toward the query's total cost.[4]
The docs single out Claude Opus 5 as a model that delegates more readily than earlier ones, which is exactly the sort of sentence you should read before giving it a loose budget.[4]
Set turns and dollars before anyone else runs it
Two options bound the loop: max_turns, which caps the number of tool-using passes, and max_budget_usd, which stops the run at an estimated spend. Neither has a default. A loop that fixes a well-scoped bug ends quickly.
An open-ended prompt like “improve this codebase” can run until your credit card gives up, and Anthropic itself calls a budget a good default for production agents.[3] For the bigger picture on orchestrating several agents, see our guide to agentic workflow patterns.
| Result subtype | What happened | Has a result field |
|---|---|---|
| success | Claude finished the task | Yes |
| error_max_turns | Hit the turn limit first | No |
| error_max_budget_usd | Hit the spend limit first | No |
| error_during_execution | Something interrupted the loop, such as a canceled request | No |
| error_max_structured_output_retries | No valid structured output within the retry limit | No |
Source: Anthropic, How the agent loop works. Every subtype carries cost, usage, turn count and session ID.
Two details save debugging time. A single-shot query() raises an error after yielding an error result, so wrap the loop in a try block. And the budget check runs after each response arrives, so the response that crosses the cap still completes and counts.
Spend can pass the cap by one response plus whatever running subagents spend before they stop.[3] A budget cap here is a speed bump, not a wall. Leave headroom.
Takeaway
Set max_turns and max_budget_usd in the first version you commit, not the second. Both default to no limit, and a subagent tree can spend faster than one agent can.
Two defaults change the moment you leave your laptop
First, the system prompt. Since v0.1.0 the SDK uses a minimal system prompt instead of Claude Code's. To get the old behavior, you ask for the claude_code preset explicitly.[5] Second, filesystem settings. Omit settingSources and the SDK loads your user, project and local settings, including CLAUDE.md files and custom commands, exactly as the CLI would.[5]
On your machine that is a feature. In CI, on a server, or in anything multi-tenant, it means your personal config leaks into the run. Anthropic's advice is to pass an empty list for those cases, and to upgrade Python first, because versions through 0.1.59 treated an empty list the same as omitting the option.[5]
Then there are the rules about who can log in. Anthropic does not allow third-party developers, unless previously approved, to offer claude.ai login or its rate limits in products built on the SDK.[1]
You authenticate with an API key, or route through Amazon Bedrock, Claude Platform on AWS, Google Cloud or Microsoft Foundry using environment variables such as CLAUDE_CODE_USE_BEDROCK=1.[2]
And you can't call your product “Claude Code.” The branding rules allow “Claude Agent” or “Your Agent Powered by Claude” and forbid names that imitate Claude Code.[1]
Side note
When the SDK is the wrong tool
My read: the Agent SDK is the right choice when the agent's job is to touch files and run commands, and the wrong choice when you are building a chat feature or a simple prompt pipeline.
For those, the Client SDK is lighter, and you don't inherit a coding agent's appetite for tools. It is also the wrong choice if you need non-Claude models.
Cursor launched its own Agent SDK on October 20, 2026, where tools are TypeScript functions and prompts are Markdown, and where one command, agent-sdk deploy, hosts the agent on Cursor's infrastructure.[8] It is a different product with a different bet, and we compare the two companies' coding agents in Claude Code vs Cursor.
The pattern I would copy is the dull one. Start with a read-only agent: three tools, plan mode, a turn cap of ten. Watch what it asks for.
Widen permissions one tool at a time, and write each widening as a hook you can read in a diff. The MCP security problem is a preview of what happens when an agent's toolbox grows faster than anyone reviews it.
That's the thing to take away. The SDK hands you a capable worker, and the interesting engineering is everything you decide it can't do.
Primary sources
- 1.PrimaryAnthropic, "Agent SDK overview". Checked November 18, 2026. What the SDK is, the four-way comparison with the CLI, Client SDK and Managed Agents, capabilities, the claude.ai login restriction and branding rules.
- 2.PrimaryAnthropic, "Agent SDK quickstart". Checked November 18, 2026. Install commands, Python 3.10+ and Node.js 18.14+ prerequisites, ANTHROPIC_API_KEY, third-party provider variables, the quickstart agent code and the tools versus allowedTools distinction.
- 3.PrimaryAnthropic, "How the agent loop works". Checked November 18, 2026. The loop cycle, built-in tools, permission modes, maxTurns and maxBudgetUsd, result subtypes, hooks and the budget-overshoot behavior.
- 4.PrimaryAnthropic, "Subagents in the SDK". Checked November 18, 2026. AgentDefinition fields, model aliases, context isolation, default depth of 3 and concurrency of 20, spend counting and the Opus 5 delegation note.
- 5.PrimaryAnthropic, "Migrate to Claude Agent SDK". Checked November 18, 2026. The rename from the Claude Code SDK, old and new package names, the v0.1.0 breaking changes and the settingSources default.
- 6.PrimaryAnthropic, "Claude Code model configuration". Checked November 18, 2026. Model aliases and what opus, sonnet and haiku resolve to on the Anthropic API.
- 7.PrimaryAnthropic, "Claude Code overview". Checked November 18, 2026. Claude Code surfaces and the note that cloud scheduled tasks were formerly called routines.
- 8.PrimaryCursor, "Introducing the Agent SDK". October 20, 2026. Cursor's own agent framework: TypeScript tools, Markdown prompts and the agent-sdk deploy command.
Frequently asked questions
- What is the Claude Agent SDK?
- The Claude Agent SDK is Anthropic's library for embedding Claude Code's agent loop in your own Python or TypeScript application. It gives your program the built-in tools (file reads and edits, shell commands, web search), hooks, subagents, MCP connections, permissions and sessions that Claude Code uses. You pass a prompt and options to query(), and the SDK streams back messages until Claude finishes the task.
- Is the Claude Agent SDK the same as the Claude Code SDK?
- Yes, it is the renamed Claude Code SDK. The Python package changed from claude-code-sdk to claude-agent-sdk, the TypeScript package from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk, and the Python options class from ClaudeCodeOptions to ClaudeAgentOptions. Anthropic's stated reason is the SDK's broader capabilities for building agents beyond coding tasks.
- How do you install the Claude Agent SDK?
- Run pip install claude-agent-sdk for Python 3.10+ or npm install @anthropic-ai/claude-agent-sdk for Node.js 18.14+. Both packages bundle a native Claude Code binary, so most installs need no separate Claude Code install. Set ANTHROPIC_API_KEY in the shell that runs your agent, because the SDK does not load .env files on its own.
- Can users of my app sign in with their Claude account?
- No, not unless Anthropic has approved it beforehand. Anthropic states that third-party developers may not offer claude.ai login or its rate limits in products built on the Claude Agent SDK. Use API key authentication, or the Amazon Bedrock, Google Cloud, Microsoft Foundry or Claude Platform on AWS routes the quickstart describes.
- How do you stop a Claude Agent SDK agent from running up a bill?
- Set maxTurns (max_turns in Python) and maxBudgetUsd (max_budget_usd), because neither has a default limit. When a cap is hit, the run ends with an error_max_turns or error_max_budget_usd result. Leave headroom on the budget, since the response that crosses the cap still completes and counts, so spend can pass the cap by the cost of that one response.
- What is the difference between the Agent SDK and the Client SDK?
- With the Client SDK you call the Claude API directly and write the tool loop yourself, or use the beta tool runner. With the Agent SDK the loop, the built-in tools and the context management already exist, because it runs Claude Code's engine inside your process. Choose the Client SDK for a custom product flow and the Agent SDK when you want a worker that reads, edits and runs things.
Written by
Tech Talk News Editorial
Computer engineering background. Writes about software, AI, markets, and real estate, and the places where the three meet.
More about the author