Claude SDK Guide: Agent SDK vs Client SDKs Explained

The Claude SDK that most developers are searching for in 2026 is the Claude Agent SDK: Anthropic's Python and TypeScript library that packages the full Claude Code agent (built-in file tools, bash execution, web search, MCP support, and the agent loop) so you can run it inside your own applications. It is a different product from the Anthropic client SDKs (anthropic on PyPI, @anthropic-ai/sdk on npm), which are thin wrappers around the raw Claude API. This guide covers both, with exact package names, install commands, a working quickstart, and a decision table for when to use each.

What "Claude SDK" Means in 2026

"Claude SDK" refers to two distinct Anthropic products, and picking the wrong one costs you days of rebuilding infrastructure that already exists:

• The Claude Agent SDK is Claude Code as a library. It was renamed from the Claude Code SDK in late 2025 to reflect that it builds general-purpose agents, not just coding tools. One function call gives you an autonomous agent that reads files, runs commands, searches the web, and edits code on your machine.
• The Anthropic client SDKs are classic API wrappers. You construct requests to the Messages API, handle responses, and if you want tools, you define schemas and execute the calls yourself.

A useful mental model: the client SDK gives you the model, the Agent SDK gives you the agent. If your product is "send a prompt, get text or structured output back," the client SDK is lighter and simpler. If your product is "Claude autonomously performs multi-step work with tools," the Agent SDK saves you from rebuilding the loop, permissions, and context management that Anthropic already ships. For a broader look at agent tooling beyond Anthropic, see our AI agent frameworks comparison.

The Claude Agent SDK

The Claude Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable from Python and TypeScript, per Anthropic's official Agent SDK docs. The exact packages as of July 2026:

Beyond the built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, and AskUserQuestion), the SDK exposes the capabilities Claude Code users already know:

• Hooks: callbacks at lifecycle points like PreToolUse, PostToolUse, and SessionStart, for validating, logging, or blocking agent actions.
• Subagents: spawn specialized child agents with their own tools and instructions; the same pattern behind Claude agent teams.
• Sessions: capture a session ID and resume later with full context, or fork a session to explore alternatives.
• Permissions: allow-list tools per query, so a code-review agent can Read and Grep but never Write.
• MCP servers: first-class Model Context Protocol support connects databases, browsers, and hundreds of integrations; our best MCP servers roundup shows what plugs in.
• Filesystem config: with default options the SDK loads skills, commands, and CLAUDE.md memory from .claude/ directories, so an agent inherits your project conventions.

Quickstart: Your First Agent in 10 Lines

A working Agent SDK program is one import and one async loop. Set ANTHROPIC_API_KEY in your environment, then run this Python example from the official quickstart:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)

asyncio.run(main())

That is the entire agent: Claude reads the file, locates the bug, and edits it, streaming progress messages as it works. The TypeScript version is the same shape with for await (const message of query({...})). Compare that with the client SDK, where the equivalent behavior means defining tool schemas, executing each tool call, feeding results back, and looping until the model stops asking for tools.

The Anthropic Client SDKs

The Anthropic client SDKs provide direct access to the Claude API in seven languages: Python (anthropic on PyPI), TypeScript (@anthropic-ai/sdk on npm), plus Java, Go, Ruby, C#, and PHP, per the official client SDK docs. You call client.messages.create() with a model ID and messages array, and you get the raw response back.

Client SDKs are the right tool when you need precise control or no agentic behavior at all: classification, summarization, extraction, chat backends, batch processing, and pipelines where your code orchestrates every step. They also expose API surface the Agent SDK does not target, such as prompt caching controls, batches, structured outputs, and token counting. Which model you call matters as much as which SDK; our Claude model comparison breaks down the current lineup and pricing tiers.

Agent SDK vs Client SDK vs Claude Code

The three surfaces share the same models but solve different problems. Anthropic's own guidance, condensed:

Anthropic notes many teams use the CLI for daily development and the Agent SDK for production, since workflows translate directly between them. There is also a fourth, hosted option (Managed Agents, a REST API where Anthropic runs the agent and sandbox), which the docs position as the production path when you do not want to operate agent infrastructure yourself. If you are still deciding whether the CLI fits your workflow at all, start with our Claude Code guide.

Authentication and Pricing

Both SDK families authenticate with an API key from the Anthropic Console, set as the ANTHROPIC_API_KEY environment variable, and bill per token at standard API rates; the SDKs themselves are free open-source software. The Agent SDK additionally supports enterprise providers via environment flags: CLAUDE_CODE_USE_BEDROCK=1 for Amazon Bedrock, CLAUDE_CODE_USE_VERTEX=1 for Google Cloud, and CLAUDE_CODE_USE_FOUNDRY=1 for Microsoft Azure.

One licensing point that surprises builders: Anthropic's docs state that, unless previously approved, third-party developers may not offer claude.ai login or claude.ai rate limits inside their products, including agents built on the Agent SDK. Your users consume your API key (or their own), not their Pro subscriptions; usage-limit questions for the consumer apps are a separate topic we cover in the Claude Pro guide.

Limitations and When Not to Use It

The Agent SDK is not the right choice for every Claude integration, and using it where a client SDK belongs adds real overhead:

• Single-call workloads. For classification, summarization, or extraction, the agent harness is dead weight; a direct messages.create() call is faster, cheaper, and easier to test.
• Language coverage. The Agent SDK ships only in Python and TypeScript as of July 2026. Java, Go, Ruby, C#, and PHP shops either use the client SDKs or call the Agent SDK across a process boundary.
• It runs on your infrastructure. The agent executes bash and edits files in your process's environment, so sandboxing, resource limits, and cleanup are your responsibility. Autonomy plus filesystem access deserves the same caution as any agent runtime.
• Cost is open-ended. Agentic loops consume tokens across many model calls and tool results. Budget controls, permission allow-lists, and hook-based guardrails are worth wiring in before production, not after.

Related Guides

• Claude Code Guide: Everything You Need to Know
• Claude Agent Teams: Multi-Agent Orchestration Guide
• Best MCP Servers for Claude Code
• AI Agent Frameworks Compared in 2026