Claude Agent SDK Development Guide

Build production AI agents that autonomously read files, run commands, search the web, edit code, and more.

Overview

The Claude Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript. It differs from the Anthropic Client SDK: with the Client SDK you implement the tool loop yourself; with the Agent SDK, Claude handles tool execution autonomously.

Quick Reference

Installation

# Step 1: Install Claude Code (required runtime)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux/WSL
# or: npm install -g @anthropic-ai/claude-code

# Step 2: Install SDK
pip install claude-agent-sdk        # Python
npm install @anthropic-ai/claude-agent-sdk  # TypeScript

Authentication

export ANTHROPIC_API_KEY=your-api-key
# Alternative providers:
# export CLAUDE_CODE_USE_BEDROCK=1  (Amazon Bedrock)
# export CLAUDE_CODE_USE_VERTEX=1  (Google Vertex AI)

Basic Usage

# Python
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"],
            permission_mode="acceptEdits"
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

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

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

Built-in Tools

| Tool | Description | |------|-------------| | Read | Read any file (text, images, PDFs, notebooks) | | Write | Create new files | | Edit | Make precise edits to existing files | | Bash | Run terminal commands, scripts, git | | Glob | Find files by pattern (**/*.ts) | | Grep | Search file contents with regex | | WebSearch | Search the web | | WebFetch | Fetch and parse web pages | | Task | Spawn subagents for parallel work |

Permission Modes

| Mode | Behavior | |------|----------| | default | Standard permission checks | | acceptEdits | Auto-approve file edits | | bypassPermissions | No permission prompts (use cautiously) | | plan | Planning mode, no execution |

Key Configuration Options

ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Bash"],  # Tool access
    disallowed_tools=["WebSearch"],           # Block specific tools
    system_prompt="You are a Python expert",  # Custom instructions
    permission_mode="acceptEdits",            # Auto-approve edits
    max_turns=10,                             # Limit iterations
    cwd="/path/to/project",                   # Working directory
    mcp_servers={"db": db_server},            # MCP integrations
    hooks={"PreToolUse": [...]},              # Lifecycle hooks
    agents={"reviewer": agent_def},           # Define subagents
    # UNIQUE FEATURES (not in other SDKs):
    setting_sources=["user", "project"],      # Load Skills from .claude/skills/
    enable_file_checkpointing=True,           # Track file changes for undo
    can_use_tool=permission_callback,         # Runtime permission decisions
    output_format={"type": "json_schema", "schema": schema},  # Structured output
)

Unique Features (Not in OpenAI/Google SDKs)

Agent Skills via settingSources

Load filesystem-based Skills (SKILL.md files) to give your agent domain expertise:

options = ClaudeAgentOptions(
    setting_sources=["project"],  # Load from .claude/skills/
    allowed_tools=["Skill"]       # Enable Skill tool
)

Custom Slash Commands

Create .claude/commands/review.md:

---
allowed-tools: Read, Grep
description: Code review
---
Review the code for security and quality issues.

Use in SDK:

async for msg in query(prompt="/review src/auth.py", options=opts):
    print(msg)

File Checkpointing

Track file changes and undo them:

options = ClaudeAgentOptions(
    enable_file_checkpointing=True,
    extra_args={"replay-user-messages": None}  # Get checkpoint UUIDs
)

async with ClaudeSDKClient(options) as client:
    await client.query("Refactor auth.py")
    async for msg in client.receive_response():
        if isinstance(msg, UserMessage) and msg.uuid:
            checkpoint_id = msg.uuid  # Save for later

# Later: rewind files
async with ClaudeSDKClient(ClaudeAgentOptions(
    enable_file_checkpointing=True,
    resume=session_id
)) as client:
    await client.query("")
    async for msg in client.receive_response():
        await client.rewind_files(checkpoint_id)
        break

Runtime Permissions with canUseTool

Dynamic permission decisions per tool call:

async def can_use_tool(tool: str, input: dict, context: dict):
    if tool == "Write" and "/config/" in input.get("file_path", ""):
        return {"behavior": "deny", "message": "Config files protected"}
    return {"behavior": "allow", "updatedInput": input}

options = ClaudeAgentOptions(can_use_tool=can_use_tool)

Cost Tracking

Track per-message token usage and costs:

async for message in query(prompt="Task", options=opts):
    if message.type == "assistant" and hasattr(message, "usage"):
        print(f"Tokens: {message.usage}")
    if message.type == "result":
        print(f"Total cost: ${message.total_cost_usd:.4f}")

System Prompt Presets

Inherit Claude Code's system prompt:

options = ClaudeAgentOptions(
    system_prompt={
        "type": "preset",
        "preset": "claude_code",
        "append": "Always follow PEP 8."
    },
    setting_sources=["project"]  # Required to load CLAUDE.md
)

Sandbox Configuration

Control Bash execution security:

options = ClaudeAgentOptions(
    sandbox={
        "enabled": True,
        "autoAllowBashIfSandboxed": True,
        "network": {"allowLocalBinding": True}
    }
)

Core Patterns

Pattern 1: Streaming vs Single-Turn

Streaming (recommended): Persistent session, supports images, hooks, interrupts:

async def message_generator():
    yield {"type": "user", "message": {"role": "user", "content": "Analyze this"}}

async for msg in query(prompt=message_generator(), options=opts):
    print(msg)

Single-turn: One-shot queries, simpler but limited:

async for msg in query(prompt="Explain the auth flow", options=opts):
    if hasattr(msg, "result"):
        print(msg.result)

Pattern 2: Session Management

# Capture session ID
async for message in query(prompt="Start task", options=opts):
    if hasattr(message, 'subtype') and message.subtype == 'init':
        session_id = message.session_id

# Resume later
async for msg in query(
    prompt="Continue from where we left off",
    options=ClaudeAgentOptions(resume=session_id)
):
    print(msg)

Pattern 3: Subagents

from claude_agent_sdk import AgentDefinition

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep", "Task"],  # Task required for subagents
    agents={
        "code-reviewer": AgentDefinition(
            description="Expert code reviewer for security and quality",
            prompt="Analyze code quality and suggest improvements.",
            tools=["Read", "Grep", "Glob"],
            model="sonnet"  # Optional model override
        )
    }
)

Pattern 4: Hooks

from claude_agent_sdk import HookMatcher

async def block_dangerous(input_data, tool_use_id, context):
    if 'rm -rf /' in input_data.get('tool_input', {}).get('command', ''):
        return {
            'hookSpecificOutput': {
                'hookEventName': 'PreToolUse',
                'permissionDecision': 'deny',
                'permissionDecisionReason': 'Dangerous command blocked'
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={
        'PreToolUse': [HookMatcher(matcher='Bash', hooks=[block_dangerous])]
    }
)

Pattern 5: Custom MCP Tools

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("get_weather", "Get temperature for location", {"lat": float, "lon": float})
async def get_weather(args):
    # Your API call here
    return {"content": [{"type": "text", "text": f"Temperature: 72°F"}]}

weather_server = create_sdk_mcp_server(
    name="weather",
    tools=[get_weather]
)

options = ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"]
)

ClaudeSDKClient (Python Multi-Turn)

For continuous conversations with session continuity:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(options) as client:
    await client.query("What's the capital of France?")
    async for msg in client.receive_response():
        print(msg)

    # Follow-up - Claude remembers context
    await client.query("What's the population of that city?")
    async for msg in client.receive_response():
        print(msg)

Hook Events

| Event | When Triggered | Use Case | |-------|---------------|----------| | PreToolUse | Before tool executes | Block/modify operations | | PostToolUse | After tool completes | Logging, auditing | | UserPromptSubmit | Prompt submitted | Add context | | Stop | Agent stops | Cleanup | | SubagentStop | Subagent finishes | Aggregate results | | PreCompact | Before compaction | Archive transcript |

Best Practices

Context Management

Isolate per-subagent context
Use CLAUDE.md for project conventions
Periodically prune context in long sessions

Security

Start from deny-all; allowlist needed tools only
Require confirmations for sensitive actions
Block dangerous commands (rm -rf, sudo)

Tool Design

Keep tools small with clear schemas
Tools are prominent in Claude's context
Design for composability

Error Handling

from claude_agent_sdk import CLINotFoundError, ProcessError

try:
    async for msg in query(prompt="Task", options=opts):
        print(msg)
except CLINotFoundError:
    print("Install Claude Code: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Failed with exit code: {e.exit_code}")

Hosting Patterns

| Pattern | Description | Use Case | |---------|-------------|----------| | Ephemeral | New container per task | Bug fixes, one-off processing | | Long-Running | Persistent containers | Email agents, chatbots | | Hybrid | Hydrated with history | Project managers, deep research |

Official Documentation

For complete API reference:

Python: https://platform.claude.com/docs/en/agent-sdk/python
TypeScript: https://platform.claude.com/docs/en/agent-sdk/typescript
Overview: https://platform.claude.com/docs/en/agent-sdk/overview

References

Load these for detailed patterns: