Claude Agent SDK: Build Production AI Agents (2026 Guide)

What it is: The Claude Agent SDK is a Python and TypeScript library from Anthropic that lets you build production AI agents using the same tools, agent loop, and context management that power Claude Code — programmatically, from inside your own application.
Who it is for: Engineers building autonomous agents, CI/CD pipelines, bug-fixers, research bots, internal tools, and any production workload where you want Claude-driven automation in code rather than a terminal.
Best if: You want Claude Code’s capabilities (file editing, shell commands, MCP, subagents) in a library you can call from your own software.
Skip if: You’re using Claude interactively — the Claude Code CLI is the right tool. Subscribe to our free daily newsletter for ongoing SDK updates.

What is the bottom line on the Claude Agent SDK?

The Claude Agent SDK is Anthropic’s library for building production AI agents using the same machinery that powers Claude Code. Available in Python and TypeScript, install with pip install claude-agent-sdk or npm install @anthropic-ai/claude-agent-sdk. Authentication is via the standard ANTHROPIC_API_KEY environment variable (or Bedrock / Vertex AI / Azure for cloud routing). As of June 15, 2026, subscription plans get a dedicated monthly Agent SDK credit pool, separate from interactive Claude usage — so you can run SDK workloads against your Pro or Max plan without burning through your conversational limits.

What are the key takeaways?

• Python: pip install claude-agent-sdk. TypeScript: npm install @anthropic-ai/claude-agent-sdk.
• Same capabilities as Claude Code — built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, etc.) plus the agent loop.
• Hooks: callback into the agent lifecycle (PreToolUse, PostToolUse, SessionStart, etc.).
• Subagents: spawn specialized agents from your main agent. Code-reviewer, researcher, planner.
• MCP support: connect to external systems (databases, browsers, APIs).
• Sessions: maintain context across multiple queries; resume or fork sessions.
• Agent SDK credits launching June 15, 2026 — lets subscription users run SDK workloads inside their plan quota.
• Open-source code samples on GitHub for both languages.

What is the Claude Agent SDK exactly?

The Agent SDK gives you Claude Code as a library. Where the Claude Code CLI is the interactive shell you type into, the Agent SDK is the same engine exposed as a programmatic interface that you call from Python or TypeScript code.

The simplest possible Python example:

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())

The equivalent TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

Five lines, and Claude is now an autonomous agent inside your codebase. It reads the file, finds the bug, makes the edit, and reports back. You didn’t implement a tool loop. You didn’t manage retries. You didn’t write any glue code — the SDK handled all of it.

How do you install the Claude Agent SDK?

Python:

pip install claude-agent-sdk

TypeScript / Node.js:

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

The TypeScript SDK bundles the native Claude Code binary for your platform as an optional dependency, so you don’t have to install Claude Code separately. Python expects you to install Claude Code separately if you want to invoke it as a subprocess.

Then set your API key (one-time):

# macOS / Linux / WSL
export ANTHROPIC_API_KEY=sk-ant-...

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Get your key from console.anthropic.com. For setting it persistently across sessions, add the export to your ~/.bashrc, ~/.zshrc, or PowerShell $PROFILE.

How do you authenticate the Agent SDK with Bedrock, Vertex AI, or Azure?

Enterprise customers who route Claude usage through a cloud provider can authenticate the SDK accordingly:

• Amazon Bedrock: export CLAUDE_CODE_USE_BEDROCK=1 and configure AWS credentials with the standard AWS CLI profile.
• Claude Platform on AWS: export CLAUDE_CODE_USE_ANTHROPIC_AWS=1 and set ANTHROPIC_AWS_WORKSPACE_ID, then configure AWS credentials.
• Google Vertex AI: export CLAUDE_CODE_USE_VERTEX=1 and authenticate with gcloud auth application-default login.
• Microsoft Azure (Foundry): export CLAUDE_CODE_USE_FOUNDRY=1 and configure Azure credentials.

Note: as of May 2026, Anthropic does not allow third-party developers to offer claude.ai login or use subscription rate limits to power external products built on the Agent SDK. You must use API-key auth or one of the cloud providers above.

What built-in tools does the Agent SDK include?

Tool	What it does
Read	Read any file in the working directory
Write	Create new files
Edit	Make precise edits to existing files
Bash	Run terminal commands, scripts, git operations
Monitor	Watch a background script and react to each output line as an event
Glob	Find files by pattern (**/*.ts, src/**/*.py)
Grep	Search file contents with regex
WebSearch	Search the web for current information
WebFetch	Fetch and parse web page content
AskUserQuestion	Ask the user clarifying questions with multiple choice options
Agent	Spawn a subagent (must be in allowedTools to use subagents)

You pass the subset of tools you want your agent to have access to via the allowed_tools (Python) or allowedTools (TypeScript) option. Anything not allowed isn’t even available to the model — this is the primary permission mechanism.

What are Agent SDK hooks and how do you use them?

Hooks are callback functions that fire at specific points in the agent lifecycle. They let you validate, log, block, or transform agent behavior without modifying the SDK itself.

• PreToolUse — fires before any tool is invoked. Use to block destructive operations.
• PostToolUse — fires after a tool completes. Use to audit, transform results, or react.
• Stop — fires when the agent terminates.
• SessionStart / SessionEnd — fires at session boundaries.
• UserPromptSubmit — fires when a user prompt arrives. Use for input validation.

A common hook pattern: log every file edit to an audit file. The PostToolUse hook with a matcher of Edit|Write writes to ./audit.log on every successful file change. This gives you a full audit trail with zero changes to your agent code.

How do subagents work in the Agent SDK?

Subagents are specialized agents your main agent can spawn to handle focused subtasks. The main agent delegates work and the subagent reports back with results. Use cases:

• Code reviewer subagent — main agent calls it on each PR diff.
• Researcher subagent — finds relevant docs or sources before the main agent implements.
• Planner subagent — produces a structured plan that the main agent then executes.
• Test-writer subagent — writes tests in parallel while the main agent implements code.

Define a subagent with the agents option:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep", "Agent"],
    agents={
        "code-reviewer": AgentDefinition(
            description="Expert code reviewer for quality and security reviews.",
            prompt="Analyze code quality and suggest improvements.",
            tools=["Read", "Glob", "Grep"],
        )
    },
)

Then prompt your main agent: “Use the code-reviewer agent to review this codebase.” The main agent invokes the subagent via the Agent tool, passes context, and integrates the result.

How does the Agent SDK work with MCP servers?

The SDK is MCP-native. Pass an mcp_servers dict (Python) or mcpServers object (TypeScript) with the servers you want your agent to use. Common examples:

options=ClaudeAgentOptions(
    mcp_servers={
        "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]},
        "github": {"command": "npx", "args": ["@modelcontextprotocol/server-github"]},
        "notion": {"command": "npx", "args": ["@modelcontextprotocol/server-notion"]}
    }
)

Now your agent can drive a browser via Playwright, manage GitHub issues, or read/write Notion pages — all through the same conversational interface. See modelcontextprotocol.io for the full ecosystem of available MCP servers.

How do Agent SDK sessions work?

Sessions maintain context across multiple queries. Claude remembers files read, analysis done, and conversation history. You can resume a session by ID or fork it to explore different approaches in parallel.

Capture a session ID from the first query, then resume in a second query:

# First query
async for message in query(prompt="Read the auth module"):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        session_id = message.data["session_id"]

# Resume with full context
async for message in query(
    prompt="Now find all places that call it",
    options=ClaudeAgentOptions(resume=session_id),
):
    print(message)

Session state is stored as JSONL on your filesystem. This makes sessions portable — you can ship them around in your infra, archive them for compliance, or feed them into your own analytics.

How does the Agent SDK compare to other Claude tools?

Tool	Best for	Tool execution	Runs in
Agent SDK	Production agents in code	Built-in (Claude handles it)	Your process, your infra
Claude Client SDK	Direct API access with custom tool loops	You implement it	Your process, your infra
Claude Code CLI	Interactive development	Built-in	Your terminal
Managed Agents	Production agents on Anthropic infra	Built-in	Anthropic-managed sandbox

Decision shortcut:

• Interactive coding → Claude Code CLI
• Production agent inside your infra → Agent SDK
• Production agent without managing infra → Managed Agents (Anthropic-hosted REST API)
• Direct API with custom tool execution → Client SDK

A common path: prototype with the Agent SDK locally, then move to Managed Agents for production where you don’t want to operate sandbox or session infrastructure yourself.

What does the new Agent SDK credits tier mean?

Starting June 15, 2026, Anthropic introduces an “Agent SDK credit” pool separate from your interactive Claude usage. Practical implication: subscription users (Pro, Max, Team, Enterprise) get a monthly Agent SDK allowance for running SDK workloads against their plan, without burning through their interactive Claude quota.

This is partly a response to the rise of third-party Agent SDK-powered frameworks (OpenClaw, Clawdbot, and similar) that were consuming subscription quotas at rates Anthropic hadn’t priced for. The new credit pool gives Anthropic a cleaner way to meter programmatic usage while letting subscribers run SDK workloads natively.

Plan-by-plan Agent SDK credit allowances (estimated, verify on Anthropic’s pricing page):

• Claude Pro: ~$20 of Agent SDK credit per month
• Claude Max 5×: ~$100 / month
• Claude Max 20×: ~$400 / month
• Team and Enterprise: per-seat allowances scaling with seat count

Once you exhaust the credit, programmatic usage stops unless you enable “extra usage” billing (charged at standard pay-as-you-go API rates).

Frequently asked questions

Is the Claude Agent SDK free?
The SDK library is free and open source. Usage is metered — either via your API key (pay-as-you-go) or against your subscription’s Agent SDK credit pool starting June 15, 2026.

Which language should I use, Python or TypeScript?
Both are first-class. Python is the better choice for data/ML pipelines, scientific computing, and back-end services. TypeScript is the better choice for full-stack web apps, Node.js services, and integration with the JavaScript ecosystem. Feature parity is maintained between the two.

Do I need Claude Code installed to use the Agent SDK?
For the TypeScript SDK, no — it bundles the Claude Code binary as an optional dependency. For Python, you may need Claude Code installed locally for certain features. Most basic agent workflows don’t require it.

Can I use the Agent SDK in production right now?
Yes. The SDK is generally available and used in production by many organizations. Common patterns: PR review bots, automated bug triage, scheduled research agents, internal automation, customer support routing.

What’s the difference between Agent SDK hooks and MCP servers?
Hooks are callbacks into the agent lifecycle (validate, log, block) that run inside your process. MCP servers are external tools the agent can use (browser, GitHub, databases). Different layers — both can be active in the same agent.

Can I make subagents recursively call other subagents?
Yes — subagents that include the Agent tool in their allowedTools can spawn their own subagents. This is powerful but can quickly burn tokens; use it deliberately and set max_tokens ceilings.

How do I track Agent SDK costs?
For API-key auth: Anthropic Console → Usage tab, broken out by workspace. The “Claude Code” workspace that auto-creates on first login is where SDK and CLI usage shows up. For cloud-provider auth: use your cloud provider’s billing dashboard (AWS Cost Explorer, etc.).

Are there branding restrictions for products built on the Agent SDK?
Yes. You can say “Claude Agent” or “Powered by Claude,” but you cannot brand your product as “Claude Code” or use Claude Code visual elements. Your product should maintain its own branding. See Anthropic’s branding guidelines for full details.

Where can I see example agents built with the SDK?
Anthropic publishes demos at github.com/anthropics/claude-agent-sdk-demos — email assistant, research agent, bug-fixer, and more.

Is the Agent SDK going to replace the Claude Code CLI?
No. The CLI is the right tool for interactive development; the SDK is the right tool for programmatic agents. Many teams use both daily.

Does the Agent SDK support streaming responses?
Yes — both the Python and TypeScript SDKs are streaming-first. The query() function returns an async iterator that yields messages as they arrive, so you can render partial responses in real time. This is critical for long-running agentic tasks where you want users to see progress instead of waiting for a full completion.

Can I run the Agent SDK in serverless environments like AWS Lambda?
Yes, with caveats. Lambda’s default 15-minute timeout limits long-running agentic tasks; use Step Functions or a long-running ECS task for anything that might take longer. The Python SDK is more straightforward in Lambda than TypeScript because of the bundled-binary requirement of the TS package.

How do I handle errors in an Agent SDK workflow?
Wrap the async for message in query(...) loop in a try/except (Python) or try/catch (TypeScript). The SDK raises specific exception classes for rate limits, API errors, tool failures, and permission denials. For production, also use PreToolUse hooks to validate tool calls before they execute, catching problems before they manifest as errors.

How does the Agent SDK differ from LangChain or other agent frameworks?
LangChain is model-agnostic and lets you compose tools, agents, and chains across many LLM providers. The Claude Agent SDK is Claude-specific but ships with Claude Code’s full tool surface built in — less assembly required if Claude is your primary model. The two can be combined: many teams use LangChain for orchestration and the Agent SDK for the Claude leg.

Track every Agent SDK update in one daily email

The Agent SDK ships meaningful updates every few weeks — new tools, new hooks, new platform integrations. The Beginners in AI newsletter ships one issue every day covering what just shipped across the Claude ecosystem. Free, daily, no fluff.

Sources

• Claude Agent SDK overview — official Anthropic documentation
• Agent SDK quickstart
• Python SDK GitHub repository
• TypeScript SDK GitHub repository
• Official Agent SDK demos
• Use Agent SDK with your Claude plan — June 15 2026 credit policy
• Model Context Protocol specification
• Managed Agents — Anthropic-hosted agent infrastructure