Claude Agent SDK: Build Custom Agents in Python and TypeScript (2026 Guide)

What Is the Claude Agent SDK

The Claude Agent SDK is the runtime that powers Claude Code, packaged as a library. Anthropic shipped it as the "Claude Code SDK" in mid-2025, then renamed it to "Claude Agent SDK" in September 2025 when they realized the runtime was general-purpose, not coding-specific.

It runs in Python (3.10+) and TypeScript. Both SDKs expose the same core: an agent loop that sends prompts to Claude, executes tool calls, feeds results back, and repeats until the task completes. Built-in tools include file read, file edit, bash execution, and web search. You can add custom tools, intercept lifecycle events with hooks, connect external capabilities through MCP servers, and spawn subagents for parallel work.

Python Quickstart

Install the SDK, set your API key, and run your first agent in under 60 seconds.

pip install claude-agent-sdk    # Python 3.10+ required
export ANTHROPIC_API_KEY=your-api-key

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find all TODO comments in this repo and create a summary",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
        ),
    ):
        if hasattr(message, "content"):
            print(message.content)

asyncio.run(main())

query() is stateless. Each call starts a fresh session with no memory of previous calls. The SDK streams messages back as an async generator. Claude decides which tools to call, the SDK executes them locally, and results feed back into the next Claude turn automatically.

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

client = ClaudeSDKClient(
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],
    )
)

# First turn - Claude remembers context for subsequent turns
response = await client.send("Read the auth module and explain the token flow")

# Second turn - continues the same session
response = await client.send("Now add refresh token rotation to that flow")

ClaudeSDKClient maintains conversation state across turns. Use it for interactive applications, chatbots, and code review flows where context matters.

TypeScript Quickstart

npm install @anthropic-ai/claude-agent-sdk
npm install -D typescript @types/node tsx
export ANTHROPIC_API_KEY=your-api-key

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

const result = query({
  prompt: "Find and fix the bug in src/auth.ts",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    permissionMode: "auto",
  },
});

for await (const message of result) {
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

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

const client = new ClaudeSDKClient({
  allowedTools: ["Read", "Edit", "Bash"],
});

// Multi-turn: client preserves session state
const response1 = await client.send("What files are in the src directory?");
const response2 = await client.send("Refactor the largest file to use async/await");

The TypeScript SDK follows the same two-pattern design: query() for stateless one-shot tasks (CI scripts, automation) and ClaudeSDKClient for stateful multi-turn conversations (interactive apps, IDE integrations). A V2 preview interface (unstable_v2_prompt()) simplifies single-turn queries further by removing the async generator pattern.

Core Concepts

The Agent Loop

The core of the SDK is a loop: send prompt to Claude, Claude returns tool calls, SDK executes tools locally, results go back to Claude, repeat. This continues until Claude produces a final response with no tool calls. You do not manage this loop. The SDK handles it, including retries, context truncation, and error recovery.

Built-in Tools

The SDK ships with the same tools Claude Code uses: Read (file reading), Edit (file editing), Bash (shell commands), Glob (file search by pattern), Grep (content search), and Write (file creation). Your agent can start working immediately without implementing tool execution. Control which tools are available through the allowed_tools parameter.

Permission Modes

The SDK supports three permission modes. ask prompts the user before each tool execution. auto allows all tool calls without confirmation. Custom mode lets you define rules per tool, useful for production deployments where you want to allow reads but require approval for writes.

Custom Tools

Custom tools extend what Claude can do. Define a Python or TypeScript function, register it with the SDK, and Claude can call it like any built-in tool. Under the hood, custom tools run as in-process MCP servers, so you do not need a separate process.

from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.tools import tool, create_sdk_mcp_server

@tool(description="Look up a user by email in our database")
def lookup_user(email: str) -> dict:
    """Query the users table and return profile data."""
    user = db.users.find_one({"email": email})
    return {"name": user.name, "plan": user.plan, "created": user.created_at}

@tool(description="Send a Slack notification to a channel")
def notify_slack(channel: str, message: str) -> str:
    """Post a message to a Slack channel via webhook."""
    requests.post(SLACK_WEBHOOK, json={"channel": channel, "text": message})
    return f"Sent to #{channel}"

# Register tools as an MCP server
server = create_sdk_mcp_server([lookup_user, notify_slack])

async for msg in query(
    prompt="Find the user john@example.com and notify #support about their plan",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Bash", "lookup_user", "notify_slack"],
        mcp_servers=[server],
    ),
):
    print(msg)

The @tool decorator handles type inference, description generation, and MCP protocol compliance. Claude sees these tools alongside the built-ins and decides when to call them based on the task.

Hooks: Intercept the Agent Loop

Hooks let you inject logic at specific points in the agent loop. The SDK fires events when a tool is about to be called (PreToolUse), after a tool returns (PostToolUse), when a subagent starts or stops, when the agent is idle, and when execution finishes. You can approve, deny, or modify tool calls before they execute.

from claude_agent_sdk import query, ClaudeAgentOptions

async def audit_hook(event):
    """Log all tool calls and block destructive commands."""
    if event.type == "PreToolUse":
        tool_name = event.tool_name
        # Block rm -rf and other destructive operations
        if tool_name == "Bash" and "rm -rf" in event.tool_input.get("command", ""):
            return {"action": "deny", "reason": "Destructive command blocked"}
        # Log everything else
        log.info(f"Tool call: {tool_name}", extra=event.tool_input)
        return {"action": "allow"}
    if event.type == "PostToolUse":
        log.info(f"Tool result: {event.tool_name}", extra={"output_length": len(str(event.result))})

async for msg in query(
    prompt="Clean up unused files in the project",
    options=ClaudeAgentOptions(
        hooks=[audit_hook],
        allowed_tools=["Read", "Bash", "Glob", "Grep"],
    ),
):
    print(msg)

Hooks are the mechanism for building production-grade agents. Use PreToolUse for permission gates, cost tracking, and rate limiting. Use PostToolUse for logging, alerting, and result validation. Hooks execute synchronously in the agent loop, so a denied tool call stops that tool without affecting the overall agent run.

Subagents

Subagents are separate agent instances that your main agent can spawn for focused subtasks. Each subagent gets its own context window. Multiple subagents run concurrently. This is the same pattern behind Claude Code's Agent Teams feature.

from claude_agent_sdk import query, ClaudeAgentOptions

# Main agent delegates subtasks to subagents
async for msg in query(
    prompt="""Review this PR:
    1. Spawn a subagent to check code style
    2. Spawn a subagent to run security analysis
    3. Spawn a subagent to verify test coverage
    Combine results into a single review.""",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Bash", "Grep", "Glob", "subagent"],
        max_subagents=3,
    ),
):
    print(msg)

Each subagent operates in its own context window, so the security scanner does not pollute the style checker's context and vice versa. Running 3 subagents concurrently on a code review that would take minutes sequentially can finish in seconds. The main agent aggregates results once all subagents complete.

MCP Integration

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. The Claude Agent SDK has MCP support built in. Connect any MCP server and your agent gains its capabilities without code changes.

from claude_agent_sdk import query, ClaudeAgentOptions

async for msg in query(
    prompt="Search the codebase for authentication vulnerabilities",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Bash", "Grep", "mcp__warpgrep__search"],
        mcp_servers=[
            {
                "name": "warpgrep",
                "type": "stdio",
                "command": "npx",
                "args": ["-y", "@anthropic-ai/warpgrep-mcp"],
            }
        ],
    ),
):
    print(msg)

MCP servers can provide tools, resources (data your agent can read), and prompts (reusable templates). The SDK handles MCP server lifecycle: starting the process, maintaining the connection, and shutting it down when the agent finishes. Add a new MCP server and your agent gains new capabilities without touching your code.

Sessions and State

Every query() call without a resume parameter starts a fresh session. To continue a conversation, capture the session_id from the init message and pass it back on the next call.

from claude_agent_sdk import query, ClaudeAgentOptions

session_id = None

# First call - capture session_id
async for msg in query(
    prompt="Read the database schema and summarize the tables",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
    if hasattr(msg, "session_id"):
        session_id = msg.session_id

# Second call - resume with context
async for msg in query(
    prompt="Now add a migration to add an 'archived' column to the users table",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Write", "Bash"],
        resume=session_id,
    ),
):
    print(msg)

Session state includes conversation history, tool results, and the agent's understanding of the codebase. Resuming is cheaper than starting fresh because the agent does not need to re-read files it already processed.

Claude Agent SDK vs OpenAI Agents SDK

Both SDKs let you build AI agents. They take fundamentally different approaches.

The Claude Agent SDK is a runtime. You get the agent loop, tool execution, context management, and subagent orchestration out of the box. The OpenAI Agents SDK is an orchestration layer: lightweight, focused on agent handoffs and coordination, with tools running on OpenAI's infrastructure. Choose Claude's SDK if you want local execution and fine-grained control. Choose OpenAI's if you want managed infrastructure and a visual builder.

Use Cases

Frequently Asked Questions

What is the Claude Agent SDK?

The Claude Agent SDK (formerly Claude Code SDK) is a Python and TypeScript library from Anthropic. It provides the same agent loop, tools, and context management that power Claude Code, exposed as a programmable library. Install with pip install claude-agent-sdk (Python 3.10+) or npm install @anthropic-ai/claude-agent-sdk (TypeScript).

How is it different from the Anthropic API?

The Anthropic API gives you raw model access: send messages, get responses. The Agent SDK adds the agent loop on top. It handles tool execution, context management, retries, and the prompt-tool-result cycle automatically. You define what tools the agent has access to and the SDK manages everything else.

Was the Claude Code SDK renamed?

Yes. Anthropic renamed it from "Claude Code SDK" to "Claude Agent SDK" in September 2025. The import path changed from claude_code_sdk to claude_agent_sdk in Python, and from @anthropic-ai/claude-code to @anthropic-ai/claude-agent-sdk in TypeScript. ClaudeCodeOptions became ClaudeAgentOptions. No other code changes needed.

Can I use it without Claude Code installed?

The Python package bundles the Claude Code CLI automatically. For TypeScript, you need Node.js 18+ and the npm package. No separate Claude Code installation is required.

What models does it support?

The SDK works with all Claude models. Default is the latest Claude model. You can specify a model explicitly: ClaudeAgentOptions(model="claude-opus-4-6") for Python or { model: "claude-opus-4-6" } for TypeScript.

Is there a free tier?

The SDK itself is free and open-source. You pay for Claude API usage. Anthropic's API pricing applies: per input/output token based on the model you select. No separate SDK fee.