Claude Agent SDK: Which Anthropic SDK You Need

If you searched for the Claude Code SDK and landed on something called the Claude Agent SDK, you found the right thing. It was renamed. Same library, same agent loop, new name — and there's an official migration guide for the package change.

The confusion that costs people an afternoon is a different one: Anthropic ships two completely separate SDKs, and they solve opposite problems.

Pick the wrong one and you'll either reimplement a tool loop that already exists, or pull in a whole coding agent when all you needed was a chat completion.

The Agent SDK is Claude Code, importable

The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code — programmable in Python and TypeScript. That's the whole idea. Anthropic built a coding agent, then exposed its engine as a library.

What you inherit for free:

• Built-in tools — read, write, and edit files, run shell commands, search the web
• Subagents that spin off focused subtasks
• Hooks that run your code at points in the agent lifecycle
• Permissions deciding what runs automatically and what needs approval
• Sessions that hold context across exchanges, and can be resumed or forked
• MCP for connecting external tools and data
• Skills, commands, and memory loaded from .claude/ and ~/.claude/, exactly as the CLI loads them

That last one matters more than it looks. A Claude Skill you wrote for the CLI works in an SDK agent with no changes, because both read the same directories.

The SDK is Python and TypeScript only. To drive the same loop from Go, Rust, or anything else, run the CLI as a subprocess with -p and --output-format json.

Installing it

Node.js 18+ or Python 3.10+, and an Anthropic account.

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

Both packages bundle a native Claude Code binary, so most installs need no separate Claude Code install. Two cases get no bundled binary: a pip install that falls back to the source distribution instead of a platform wheel, and an npm install that skips optional dependencies (npm ci --omit=optional). In either case, install Claude Code natively and the SDK will find it.

Authentication is an API key in the environment:

export ANTHROPIC_API_KEY=your-api-key

The SDK reads the key from the process environment and does not load .env files for you. If you keep the key in .env, load it yourself before calling the SDK. Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry are supported through their own environment flags.

One rule to know before you plan a product around this: unless Anthropic has approved it in advance, third-party developers may not offer claude.ai login or claude.ai rate limits to their own users. Agents you ship authenticate with API keys.

The smallest useful agent

The entry point is query. It returns an async iterator, so you stream messages as the agent works:

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(
            # Auto-approves these three tools. acceptEdits also auto-approves
            # Write and filesystem commands inside the working directory.
            # Unlisted tools such as Bash are still available.
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

The loop runs while Claude thinks, calls a tool, reads the result, and decides what to do next. Each iteration yields one message: reasoning, a tool call, a tool result, or the final outcome. Orchestration, tool execution, context management, and retries are handled for you.

allowed_tools is an auto-approve list, not a whitelist. It's the line in the config most worth reading carefully. By default Claude has the full Claude Code toolset. Naming tools in allowed_tools pre-approves calls to them; every tool you didn't name is still available and falls through to permission_mode and your can_use_tool callback for a decision. Listing Read, Glob, Grep doesn't give you a read-only agent. It gives you an agent whose reads never prompt, with Write, Edit, and Bash still in its toolset.

The example above makes that concrete. acceptEdits auto-approves file edits (Edit and Write) and the filesystem commands mkdir, touch, rm, rmdir, mv, cp, and sed, on paths inside the working directory or any additional directories you've configured. So Write calls and those shell commands are approved too, even though neither appears in the list.

To actually fix the tool surface, pick one of two shapes:

The asymmetry is worth memorising: deny rules remove capability, allow rules only remove friction. And allowed_tools doesn't constrain bypassPermissions at all. That mode approves every tool you haven't denied, listed or not, so if you need it, block tools with disallowed_tools. The permissions guide documents the full six-step evaluation order, including the few actions no mode auto-approves.

When the Client SDK is the right answer

Reach for the plain Anthropic SDK instead when you want the model, not an agent:

• Classification, extraction, summarisation, rewriting — one call in, one answer out
• You already have an orchestration framework and just need a model behind it
• You want tool use, but on your own terms, with your own loop and your own state

The Client SDK is a thin, well-behaved API client. The Agent SDK is an opinionated harness with a filesystem, a shell, and a mind of its own. If your task never touches files or commands, the harness is weight you're carrying for nothing.

The reverse mistake is more expensive. Teams building "an agent that reads our repo and opens a PR" on the Client SDK end up writing their own tool dispatch, their own context compaction, their own retry logic, and their own permission layer — and arrive at a worse version of what the Agent SDK already ships. If your design doc contains the phrase "then we loop until it's done", stop and look at the Agent SDK first.

Migrating from the Claude Code SDK

If you have working code on the old packages, the change is mostly a rename, and Anthropic publishes a migration guide alongside the Python and TypeScript repositories. Both carry changelogs, which are the honest place to check whether an option you depend on moved.

There's also a branding constraint worth reading before launch. Anthropic permits "Claude Agent", "Claude" inside a menu already labelled "Agents", or "YourProduct Powered by Claude". It does not permit calling your product "Claude Code" or "Claude Code Agent", or mimicking Claude Code's visual identity.

Licensing differs by layer, so don't assume one answer covers the whole stack. The Python SDK's repository is MIT. The TypeScript SDK's license reserves all rights and points to Anthropic's Commercial Terms. The Claude Code binary both packages bundle is all rights reserved whichever one you install. And calls made with an Anthropic API key fall under Anthropic's Commercial Terms of Service. We unpack that split in is Claude open source.

FAQ

Is the Claude Agent SDK the same as the Claude Code SDK?

Yes. The Claude Code SDK was renamed to the Claude Agent SDK, and the packages changed names with it. Anthropic maintains a migration guide for moving existing projects across.

What's the difference between the Claude Agent SDK and the Anthropic Python SDK?

The Anthropic Python SDK (anthropic) is an API client — you send messages, you get responses, and any tool loop is yours to write. The Claude Agent SDK (claude-agent-sdk) is an agent harness with file, shell, and search tools already wired into a loop that runs until the task finishes.

Do I need Claude Code installed to use the Agent SDK?

Usually not. Both SDKs bundle a native Claude Code binary. You only need a separate install when the bundled binary is missing — an ARM64 Windows source install, or an npm install that skipped optional dependencies.

Can I use my Claude Pro or Max subscription with the Agent SDK?

For your own use, authenticate however the docs allow. For a product you ship to other people, no: Anthropic doesn't permit third-party developers to offer claude.ai login or claude.ai rate limits without prior approval. Ship with API key authentication.

Which languages does the Agent SDK support?

Python and TypeScript as libraries. For any other language, run the Claude Code CLI as a subprocess with -p and --output-format json and parse the result.

The short version

The Agent SDK is for building things that act; the Client SDK is for things that answer. The rename from Claude Code SDK is cosmetic. The real decision is whether your task needs a loop with tools attached — and if it does, you should not be writing that loop yourself.

Most people who read a page like this never ship the agent, and the reason is rarely the SDK. It's the hour between pip install and knowing whether the idea was any good — keys, environments, a dependency that wants a different Python. Taku shortens that hour by letting you open somebody's working agent directly on your own machine and edit it from there, rather than rebuilding their environment before you can judge their idea. Taku is in Beta, and the Mac app is available now.

Still deciding what to build on rather than how to install it? Our guides to agentic AI frameworks and what an LLM agent actually is cover the layer above this one, and MCP server configuration in Claude Code covers how to give any of them access to your real tools.