Claude Agent SDK

Build production-ready applications using the Claude Agent SDK for Python.

SDK Version: This skill targets claude-agent-sdk>=0.1.6 (Python)

Overview

This skill provides patterns, examples, and best practices for building SDK applications that orchestrate Claude agents.

Quick Start

Copy the template and customize:

cp assets/sdk-template.py my-app.py

Edit my-app.py - customize agents and workflow

chmod +x my-app.py ./my-app.py

The template includes proper uv script headers, agent definitions, and async patterns.

Choosing Between query() and ClaudeSDKClient

The SDK provides two ways to interact with Claude: the query() function for simple one-shot tasks, and ClaudeSDKClient for continuous conversations.

Quick Comparison

Feature query()

ClaudeSDKClient

Conversation memory No - each call is independent Yes - maintains context across queries

Use case One-off tasks, single questions Multi-turn conversations, complex workflows

Complexity Simple - one function call More setup - context manager pattern

Hooks support No Yes

Custom tools No Yes

Interrupts No Yes - can interrupt ongoing operations

Session control New session each time Single persistent session

Important: Hooks and custom tools (SDK MCP servers) are only supported with ClaudeSDKClient , not with query() . If you need hooks or custom tools, you must use ClaudeSDKClient .

Note on Async Runtimes: The SDK works with both asyncio and anyio . The official SDK examples prefer anyio.run() for better async library compatibility, but asyncio.run() works equally well. Use whichever fits your project's async runtime.

When to Use query()

Use query() for simple, independent tasks where you don't need conversation history:

import anyio # or: import asyncio from claude_agent_sdk import query, ClaudeAgentOptions

async def analyze_file(): """One-shot file analysis - no conversation needed.""" options = ClaudeAgentOptions( system_prompt="You are a code analyzer", allowed_tools=["Read", "Grep", "Glob"], permission_mode="acceptEdits" )

async for message in query(
    prompt="Analyze /path/to/file.py for bugs",
    options=options
):
    print(message)

anyio.run(analyze_file) # or: asyncio.run(analyze_file())

Best for:

Single analysis tasks
Independent file operations
Quick questions without follow-up
Scripts that run once and exit

Key limitation: Each query() call creates a new session with no memory of previous calls.

When to Use ClaudeSDKClient

Use ClaudeSDKClient when you need conversation context across multiple interactions:

import anyio # or: import asyncio from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock

async def interactive_debugging(): """Multi-turn debugging conversation with context.""" options = ClaudeAgentOptions( system_prompt="You are a debugging assistant", allowed_tools=["Read", "Grep", "Bash"], permission_mode="acceptEdits" )

async with ClaudeSDKClient(options=options) as client:
    # First query
    await client.query("Find all TODO comments in /path/to/project")
    async for message in client.receive_response():
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(f"Claude: {block.text}")

    # Follow-up - Claude remembers the TODOs found above
    await client.query("Now prioritize them by complexity")
    async for message in client.receive_response():
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(f"Claude: {block.text}")

    # Another follow-up - still in same conversation
    await client.query("Create a plan to address the top 3")
    async for message in client.receive_response():
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(f"Claude: {block.text}")

anyio.run(interactive_debugging) # or: asyncio.run(interactive_debugging())

Best for:

Multi-turn conversations
Interactive workflows
Tasks requiring context from previous responses
Applications with interrupt capability
Orchestrators managing complex workflows

Key advantage: Claude remembers all previous queries and responses in the session.

See: examples/streaming_mode.py

Comprehensive ClaudeSDKClient examples with all patterns

Advanced: Interrupts with ClaudeSDKClient

Only ClaudeSDKClient supports interrupting ongoing operations:

import anyio # or: import asyncio from claude_agent_sdk import ClaudeSDKClient

async def interruptible_task(): async with ClaudeSDKClient() as client: await client.query("Run a long analysis on /large/codebase")

    # Start processing in background
    async with anyio.create_task_group() as tg:
        tg.start_soon(process_messages, client)

        # Simulate user interrupt after 5 seconds
        await anyio.sleep(5)
        await client.interrupt()

async def process_messages(client): async for message in client.receive_response(): print(message)

anyio.run(interruptible_task) # or: asyncio.run(interruptible_task())

Quick Decision Guide

Use query() if:

Task is self-contained
No follow-up questions needed
Each execution is independent
Simpler code is preferred

Use ClaudeSDKClient if:

Need conversation memory
Building interactive workflows
Require interrupt capability
Managing complex multi-step processes
Working with orchestrators and subagents

Core Patterns

Orchestrator with Subagents

Define a main orchestrator that delegates work to specialized subagents.

Critical requirements:

Orchestrator must use system_prompt={"type": "preset", "preset": "claude_code"} (provides Task tool knowledge)
Register agents programmatically via agents={} parameter (SDK best practice)
Orchestrator must include "Task" in allowed_tools
Match agent names exactly between definition and usage

Example:

from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions

options = ClaudeAgentOptions( system_prompt={"type": "preset", "preset": "claude_code"}, # REQUIRED for orchestrators allowed_tools=["Bash", "Task", "Read", "Write"], agents={ "analyzer": AgentDefinition( description="Analyzes code structure and patterns", prompt="You are a code analyzer...", tools=["Read", "Grep", "Glob"], model="sonnet" ), "fixer": AgentDefinition( description="Fixes identified issues", prompt="You are a code fixer...", tools=["Read", "Edit", "Bash"], model="sonnet" ) }, permission_mode="acceptEdits", model="claude-sonnet-4-5" )

See:

references/agent-patterns.md
Complete agent definition patterns
examples/agents.py
Official SDK agent examples with different agent types

System Prompt Configuration

Choose the appropriate system prompt pattern:

Orchestrator (use claude_code preset) - dict format (official examples prefer this)

system_prompt={"type": "preset", "preset": "claude_code"}

Shorthand format (equivalent, but less explicit)

system_prompt="claude_code"

Custom behavior

system_prompt="You are a Python expert..."

Extend preset with additional instructions

system_prompt={ "type": "preset", "preset": "claude_code", "append": "Additional domain-specific instructions" }

Note: The shorthand system_prompt="claude_code" is equivalent to {"type": "preset", "preset": "claude_code"} . Both are valid. Official examples prefer the dict format for explicitness.

See:

references/system-prompts.md
Complete system prompt documentation
examples/system_prompt.py
Official SDK system prompt examples

Tool Restrictions

Limit subagent tools to minimum needed:

Read-only analyzer

tools=["Read", "Grep", "Glob"]

Code modifier

tools=["Read", "Edit", "Bash"]

Test runner

tools=["Bash", "Read"]

See: references/agent-patterns.md for common tool combinations

Hooks

Intercept SDK events to control behavior:

from claude_agent_sdk import HookMatcher

options = ClaudeAgentOptions( hooks={ "PreToolUse": [ HookMatcher(matcher="Bash", hooks=[check_bash_command]) ], "PostToolUse": [ HookMatcher(matcher="Bash", hooks=[review_output]) ] } )

See:

references/hooks-guide.md
Complete hook patterns documentation
examples/hooks.py
Official SDK hook examples with all hook types

Permission Callbacks

Fine-grained control over tool usage:

async def permission_callback(tool_name, input_data, context): # Allow read operations if tool_name in ["Read", "Grep", "Glob"]: return PermissionResultAllow()

# Block dangerous commands
if tool_name == "Bash" and "rm -rf" in input_data.get("command", ""):
    return PermissionResultDeny(message="Dangerous command")

return PermissionResultAllow()

options = ClaudeAgentOptions( can_use_tool=permission_callback, permission_mode="default" )

See:

references/tool-permissions.md
Complete permission patterns and decision guide
examples/tool_permission_callback.py
Official SDK permission callback example

Workflow Templates

Building an Orchestrator

Follow these steps to build an effective orchestrator:

Define agent purposes

What specialized tasks need delegation?
What tools does each agent need?
What constraints should apply?

Create agent definitions

agents={ "agent-name": AgentDefinition( description="When to use this agent", prompt="Agent's role and behavior", tools=["Tool1", "Tool2"], model="sonnet" ) }

Configure orchestrator

options = ClaudeAgentOptions( system_prompt={"type": "preset", "preset": "claude_code"}, # CRITICAL allowed_tools=["Bash", "Task", "Read", "Write"], agents=agents, permission_mode="acceptEdits" )

Implement workflow

async with ClaudeSDKClient(options=options) as client: await client.query("Use 'agent-name' to perform task")

async for message in client.receive_response():
    # Process responses
    pass

See: examples/basic-orchestrator.py for complete working example

Loading Agents from Files

While programmatic registration is recommended, agent content can be stored in markdown files:

import yaml

def load_agent_definition(path: str) -> AgentDefinition: """Load agent from markdown file with YAML frontmatter.""" with open(path) as f: content = f.read()

parts = content.split("---")
frontmatter = yaml.safe_load(parts[1])
prompt = parts[2].strip()

# Parse tools (comma-separated string or array)
tools = frontmatter.get("tools", [])
if isinstance(tools, str):
    tools = [t.strip() for t in tools.split(",")]

return AgentDefinition(
    description=frontmatter["description"],
    prompt=prompt,
    tools=tools,
    model=frontmatter.get("model", "inherit")
)

Load and register programmatically

agent = load_agent_definition(".claude/agents/my-agent.md") options = ClaudeAgentOptions(agents={"my-agent": agent})

See: references/agent-patterns.md for complete loading pattern

Common Anti-Patterns

Avoid these common mistakes:

❌ Missing orchestrator system prompt

Orchestrator won't know how to use Task tool

options = ClaudeAgentOptions(agents={...})

✅ Correct orchestrator configuration

options = ClaudeAgentOptions( system_prompt="claude_code", agents={...} )

❌ Mismatched agent names

agents={"investigator": AgentDefinition(...)} await client.query("Use 'markdown-investigator'...") # Wrong name

✅ Exact name matching

agents={"investigator": AgentDefinition(...)} await client.query("Use 'investigator'...") # Matches

❌ Tool/prompt mismatch

system_prompt="Fix bugs you find" allowed_tools=["Read", "Grep"] # Can't fix, only read

✅ Aligned tools and behavior

system_prompt="Analyze code for bugs" allowed_tools=["Read", "Grep", "Glob"]

See: references/best-practices.md for complete anti-patterns list

Resources

references/

In-depth documentation loaded as needed:

api-reference.md
Complete Python SDK API reference (types, functions, examples)
agent-patterns.md
Agent definition patterns, tool restrictions, best practices
subagents.md
Comprehensive subagent patterns and SDK integration
system-prompts.md
System prompt configuration (preset, custom, append)
hooks-guide.md
Hook patterns for all hook types with examples
tool-permissions.md
Permission callback patterns and examples
best-practices.md
SDK best practices, anti-patterns, debugging tips
custom-tools.md
Creating custom tools with SDK MCP servers (Python-only)
sessions.md
Session management and resumption patterns (Python-only)
skills.md
Using Agent Skills with the SDK (Python-only)
slash-commands.md
Slash commands and custom command creation (Python-only)

examples/

Ready-to-run code examples from official SDK:

Getting Started:

quick_start.py
Basic query() usage and message handling (start here!)
basic-orchestrator.py
Complete orchestrator with analyzer and fixer subagents

Core Patterns:

agents.py
Programmatic agent definitions with different agent types
hooks.py
Comprehensive hook patterns (PreToolUse, PostToolUse, UserPromptSubmit, etc.)
system_prompt.py
System prompt patterns (preset, custom, append)
streaming_mode.py
Complete ClaudeSDKClient patterns with multi-turn conversations

Advanced Features:

mcp_calculator.py
Custom tools with SDK MCP server (in-process tool server)
tool_permission_callback.py
Permission callbacks with logging and control
setting_sources.py
Settings isolation and loading (user/project/local)
plugin_example.py
Using plugins with the SDK (relevant for plugin marketplace!)

assets/

Templates and validation tools:

sdk-template.py
Project template with uv script headers and agent structure
sdk-validation-checklist.md
Comprehensive checklist for validating SDK applications against best practices

When to Use This Skill

Use this skill when:

Creating new Claude Agent SDK applications
Building orchestrators with multiple subagents
Implementing programmatic agent definitions
Configuring hooks or permission callbacks
Validating/reviewing SDK code (use assets/sdk-validation-checklist.md )
Migrating from filesystem agent discovery to programmatic registration
Debugging SDK applications (agent not found, Task tool not working)
Following SDK best practices

Do not use for:

Claude Code slash commands or skills (different system)
Direct API usage without SDK
Non-Python implementations (TypeScript SDK has different patterns)

Next Steps

For Beginners

Start with examples/quick_start.py
Learn basic query() usage
Try assets/sdk-template.py
Template for new projects
Review examples/basic-orchestrator.py
See orchestrator pattern

For Intermediate Users

Explore core patterns:
examples/agents.py
Agent definitions
examples/system_prompt.py
System prompt patterns
examples/streaming_mode.py
Multi-turn conversations
examples/hooks.py
Hook patterns

For Advanced Users

Study advanced features:
examples/tool_permission_callback.py
Permission control
examples/mcp_calculator.py
Custom tools
examples/setting_sources.py
Settings management
examples/plugin_example.py
Plugin integration

Validation & Quality

Validate your code with assets/sdk-validation-checklist.md
Review against best practices in references/best-practices.md

Reference Documentation

Consult references/ as needed for detailed patterns

claude-agent-sdk

Safety Notice

Copy this and send it to your AI assistant to learn

Edit my-app.py - customize agents and workflow

Orchestrator (use claude_code preset) - dict format (official examples prefer this)

Shorthand format (equivalent, but less explicit)

Custom behavior

Extend preset with additional instructions

Read-only analyzer

Code modifier

Test runner

Load and register programmatically

Orchestrator won't know how to use Task tool

Source Transparency

Related Skills

coderabbit

agent-development

hook-development

devtools-secrets