.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
If you went looking for the Claude Code SDK and found two package names, half the tutorials importing one and the docs describing the other, here's the missing piece: Anthropic renamed it. On September 29, 2025 the Claude Code SDK became the Claude Agent SDK, a change announced in the Claude Agent SDK launch post, and the reasoning was honest enough: people kept building non-coding agents with it, so the coding name had become too small. Same product, new name, new package names and a couple of behavior changes that quietly break code written for the old one.
This article untangles the rename, then gets you to the current install commands, a minimal working example and the migration traps. It also takes a position on when you need the SDK at all, because a lot of people reaching for it would be better served by a shell script.
What the Claude Agent SDK is
The SDK is the same agent harness that powers the CLI, exposed as a library. The agent loop, the built-in tools (Read, Edit, Bash, Glob and friends), the permission system and the context management you get when you type claude in a terminal are all in there, callable from your own TypeScript or Python code. The CLI is one client of that harness. Your product can be another: a code-review bot, a support agent digging through logs, an internal tool that files tickets. Anything where you want an agent that can use tools inside software you ship.
When claude -p is enough
Before installing anything, check if you need it, because the CLI already scripts. claude -p "prompt" runs headless, takes --output-format json for machine-readable results and exits 0 or 1 like a well-behaved Unix citizen. That covers cron jobs, CI steps, git hooks and most one-shot automation, and it's how I run scheduled jobs on a server, described in the guide to running Claude Code on a VPS. My rule: if you're scripting the CLI with claude -p and it works, you don't need the SDK yet. The SDK is the right call when you're building a product: you need to process messages as they stream, make permission decisions in code, define custom tools or embed the agent inside a long-running service. You do give up the CLI's interactive conveniences, including the session resume and branching machinery covered in the Claude Code sessions guide, and take on responsibility for the equivalents yourself.
Package names, old and new
The rename hit both languages. TypeScript moved from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk; Python moved from claude-code-sdk to claude-agent-sdk. The old names are still all over tutorials and Stack Overflow answers, which is exactly how most people end up confused, so treat any snippet importing claude-code-sdk as pre-rename material and translate as you read. Installing the current packages:
npm install @anthropic-ai/claude-agent-sdk # Node.js 18+
pip install claude-agent-sdk # Python 3.10+Both packages bundle a native Claude Code binary, so you don't need the CLI installed separately for the SDK to work. One less deployment step than you'd guess.
A minimal TypeScript example
The core primitive is query(), an async generator you iterate for messages as the agent works:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find the failing test in this repo and fix it",
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits"
}
})) {
console.log(message);
}Run it with ANTHROPIC_API_KEY exported and you'll watch the message stream go by: the agent's reasoning, each tool call and its result, then a final result message with the outcome. Those two options are the ones to internalize first. allowedTools is the capability fence (this agent can read and edit but never run shell commands) and permissionMode decides how much gets waved through automatically, the same concept the CLI exposes as its permission modes.
The Python shape
Python mirrors it with an async iterator and an options class:
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(
prompt="Find the failing test in this repo and fix it",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
),
):
print(message)Note the class name: ClaudeAgentOptions. Pre-rename code says ClaudeCodeOptions, and that single identifier is the fastest way to date a Python tutorial.
Behavior changes that bite migrators
The rename shipped alongside v0.1.0, and two default changes in that release are responsible for most "it worked before" reports. First, the SDK no longer uses Claude Code's system prompt by default, so a migrated agent starts blander and less coding-focused than it was. Opting back in is explicit: systemPrompt: { type: "preset", preset: "claude_code" }. Second, the SDK stopped inheriting filesystem configuration by default. The settingSources option controls which of your user, project and local settings load, and an empty list keeps the agent fully isolated, which is the new default posture. The visible symptom is an agent that ignores the project's conventions because it never read the CLAUDE.md file the CLI would have loaded automatically.
Both defaults are sensible for products (you generally don't want a deployed agent picking up config from wherever it happens to run) and both are startling mid-migration. The official migration guide lists the full set of changes; these two are the ones I've watched cost people an afternoon.
Authentication for SDK apps
One rule matters here and it's documented plainly: an API key (or a cloud provider route through Bedrock, Vertex or Foundry) is how SDK applications authenticate, and claude.ai subscription login is not allowed for products built on the SDK. Your Pro or Max plan covers you typing at the CLI; it doesn't cover an agent you ship to other people. Budget for API billing from the first prototype and the economics of your product stay honest. Deployment-wise an SDK agent is an ordinary process wanting a home with a steady connection, and a small VPS suits it well; a Claude Code VPS deploys instantly on NVMe with unmetered bandwidth, which is the profile a chatty agent process appreciates.
Where to go from here
The Agent SDK overview is the current front door and its quickstart gets a first agent running in a few minutes; from there the docs cover custom tools, MCP integration, permission callbacks and structured streaming. Start with the smallest agent that does one real task, keep allowedTools tight and grow capabilities as the agent proves itself. And if all you wanted was to automate a prompt on a schedule, close this tab and write the claude -p one-liner. The SDK will still be here when you outgrow it.
