claude-agent-sdk

<essential_principles>

Claude Agent SDK Overview

The Claude Agent SDK gives agents the same tools that power Claude Code: file operations, bash commands, web search, and more. Build autonomous agents that read files, run commands, search the web, edit code, and verify their work.

Two Ways to Query

Function	Session	Best For
query()	New each time	One-off tasks, automation
ClaudeSDKClient	Continuous	Conversations, follow-ups, hooks

Key Difference: query() is simpler but doesn't support hooks, interrupts, or custom tools. Use ClaudeSDKClient for advanced features.

Agent Loop Pattern

Agents operate in a feedback loop:

gather context → take action → verify work → repeat

Installation

Python:

uv add claude-agent-sdk

TypeScript:

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

Requirements:

• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• ANTHROPIC_API_KEY environment variable set

Quick Start

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

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

asyncio.run(main())

</essential_principles>

What would you like to do?

1. Create a new agent - Build an agent from scratch
2. Add custom tools - Create tools with @tool decorator or MCP servers
3. Add hooks - Intercept tool calls for logging, validation, or modification
4. Configure permissions - Control what tools can do
5. Create subagents - Define specialized agents for parallel work
6. Control browsers - Chrome extension, dev-browser skill
7. Get API reference - Python or TypeScript SDK details

Wait for response before proceeding.

Response	Load
1, "create", "new", "build"	workflows/create-agent.md
2, "tools", "custom", "@tool"	references/custom-tools.md
3, "hooks", "intercept"	references/hooks.md
4, "permissions", "can_use_tool"	references/permissions.md
5, "subagent", "parallel"	references/subagents.md
6, "browser", "chrome", "automation"	references/browser-control.md
7, "python", "reference"	references/python-sdk.md
7, "typescript", "reference"	references/typescript-sdk.md
"built-in", "tools"	references/built-in-tools.md
"message", "types"	references/message-types.md
"best practices", "patterns"	references/best-practices.md
"error", "troubleshoot"	references/troubleshooting.md

<quick_reference>

ClaudeAgentOptions (Key Fields)

ClaudeAgentOptions(
    # Tools
    allowed_tools=["Read", "Write", "Bash"],  # Built-in tools to enable
    disallowed_tools=["WebSearch"],           # Tools to block

    # Prompts
    system_prompt="You are...",               # Custom system prompt
    # Or use preset: {"type": "preset", "preset": "claude_code", "append": "..."}

    # MCP Servers
    mcp_servers={"calc": my_server},          # MCP server configs

    # Permissions
    permission_mode="acceptEdits",            # default | acceptEdits | plan | bypassPermissions
    can_use_tool=my_handler,                  # Custom permission callback

    # Execution
    cwd="/path/to/project",                   # Working directory
    max_turns=10,                             # Limit iterations
    env={"API_KEY": "..."},                   # Environment variables

    # Advanced
    hooks={"PreToolUse": [...]},              # Behavior hooks
    agents={"researcher": AgentDef(...)},     # Subagents
    sandbox={"enabled": True},                # Sandbox settings
    setting_sources=["project"],              # Load .claude settings
)

Built-in Tools

Tool	Purpose
Read	Read files (text, images, PDFs, notebooks)
Write	Create new files
Edit	Modify existing files with search/replace
Bash	Run terminal commands
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
NotebookEdit	Edit Jupyter notebooks
TodoWrite	Manage task lists
KillShell	Kill background shells
ExitPlanMode	Exit planning mode

Message Types

# All messages
Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage

# Content blocks in AssistantMessage
ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock

Error Types

from claude_agent_sdk import (
    CLINotFoundError,      # Claude Code CLI not installed
    CLIConnectionError,    # Connection failed
    ProcessError,          # CLI process failed
    CLIJSONDecodeError,    # JSON parsing failed
)

</quick_reference>

<thinking_config>

Thinking & Effort Configuration

Control agent thinking depth via the effort parameter rather than prompt-level instructions like "think carefully":

Use Case	Effort	Notes
Quick lookups, simple edits	low	Minimal thinking overhead
Standard development	medium	Default for most agents
Complex architecture, security	high	Deeper reasoning
Deep research, long-horizon	max	Maximum thinking budget

# Adaptive thinking (recommended for Claude 4.6)
options = ClaudeAgentOptions(
    model="claude-opus-4-6",  # or claude-sonnet-4-6
    # Effort is controlled at the API level, not in the agent options
)

Avoid adding "think carefully" or "be thorough" to agent system prompts—Claude 4.6 calibrates thinking depth automatically based on task complexity.

</thinking_config>

Common Patterns

File Operations Agent

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Glob", "Grep"],
    permission_mode="acceptEdits",
    cwd="/path/to/project"
)

Code Review Agent

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],  # Read-only
    system_prompt="Review code for bugs, security issues, and style"
)

Research Agent

options = ClaudeAgentOptions(
    allowed_tools=["WebSearch", "WebFetch", "Write"],
    max_turns=20  # Allow more iterations for research
)

Interactive Chat with Tools

async with ClaudeSDKClient(options) as client:
    await client.query("What files are in this directory?")
    async for msg in client.receive_response():
        print(msg)

    # Follow-up - Claude remembers context
    await client.query("Show me the largest one")
    async for msg in client.receive_response():
        print(msg)