Claude Agent SDK A Comprehensive Tutorial

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

pip install claude-agent-sdk

export ANTHROPIC_API_KEY='your-api-key-here'

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="What is 2 + 2?"):
        print(message)

anyio.run(main)

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

async def process_data():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Bash"],
        permission_mode='acceptEdits',  # auto-accept file edits
        cwd="/path/to/project"
    )
    
    prompt = """
    Read the data.csv file, analyze the sales trends,
    and create a summary report in markdown format.
    """
    
    async for message in query(prompt=prompt, options=options):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)

anyio.run(process_data)

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient

# Define a custom tool
@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {
        "content": [
            {"type": "text", "text": f"Hello, {args['name']}!"}
        ]
    }

# Another custom tool for calculations
@tool("calculate_roi", "Calculate ROI", {"investment": float, "return": float})
async def calculate_roi(args):
    roi = ((args['return'] - args['investment']) / args['investment']) * 100
    return {
        "content": [
            {"type": "text", "text": f"ROI: {roi:.2f}%"}
        ]
    }

# Create an MCP server with your tools
server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[greet_user, calculate_roi]
)

# Use it with Claude
async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"tools": server},
        allowed_tools=["mcp__tools__greet", "mcp__tools__calculate_roi"]
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Calculate ROI for $10,000 investment with $15,000 return")
        
        async for msg in client.receive_response():
            print(msg)

anyio.run(main)

import { ClaudeSDKClient, ClaudeAgentOptions } from '@anthropic-ai/claude-agent-sdk';

const options: ClaudeAgentOptions = {
  allowedTools: ['Read', 'Write', 'Bash', 'WebSearch'],
  systemPrompt: 'You are a helpful coding assistant.',
  maxTurns: 10
};

const client = new ClaudeSDKClient(options);

// Query the agent
await client.query('Create a Python script that analyzes CSV data');

// Process streaming responses
for await (const message of client.receiveResponse()) {
  console.log(message);
}

await client.close();

options = ClaudeAgentOptions(
    permission_mode='acceptEdits',  # Auto-accept file changes
    allowed_tools=['Read', 'Write', 'Bash']  # Limit available tools
)

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, tool, create_sdk_mcp_server

# Define email-related tools
@tool("fetch_emails", "Fetch unread emails", {})
async def fetch_emails(args):
    # Your email API integration here
    emails = get_unread_emails()
    return {"content": [{"type": "text", "text": str(emails)}]}

@tool("send_email", "Send an email", {"to": str, "subject": str, "body": str})
async def send_email(args):
    # Your email sending logic
    send_email_via_api(args['to'], args['subject'], args['body'])
    return {"content": [{"type": "text", "text": "Email sent successfully"}]}

@tool("categorize_email", "Categorize email", {"email_id": str, "category": str})
async def categorize_email(args):
    # Your categorization logic
    return {"content": [{"type": "text", "text": f"Categorized as {args['category']}"}]}

# Create the agent
async def email_agent():
    server = create_sdk_mcp_server(
        name="email-tools",
        version="1.0.0",
        tools=[fetch_emails, send_email, categorize_email]
    )
    
    options = ClaudeAgentOptions(
        mcp_servers={"email": server},
        system_prompt="""
        You are an email assistant. You can:
        - Fetch and read emails
        - Categorize emails by importance
        - Draft responses
        - Send emails
        Always ask for confirmation before sending emails.
        """
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("""
            Check my unread emails, categorize them by urgency,
            and draft responses to the urgent ones.
        """)
        
        async for msg in client.receive_response():
            print(msg)

anyio.run(email_agent)

# ✅ Good
"Read the sales_data.csv file, calculate total revenue by region, and create a bar chart"

# ❌ Vague
"Analyze sales"

options = ClaudeAgentOptions(
    allowed_tools=['Read', 'Bash'],  # Only read and bash, no writes
    permission_mode='ask'  # Ask before each action
)

try:
    async for message in query(prompt=my_prompt, options=options):
        process_message(message)
except Exception as e:
    logger.error(f"Agent error: {e}")

# ✅ Good: Use grep to find relevant sections
"Use grep to find all TODO comments in Python files"

# ❌ Wasteful: Loading entire large files
"Read all files and find TODOs"

from claude_agent_sdk import query, ClaudeAgentOptions

async def code_analyzer():
    options = ClaudeAgentOptions(
        allowed_tools=['Read', 'Bash'],
        cwd='/path/to/your/react/project'
    )
    
    prompt = """
    Analyze this React codebase:
    1. Find all useState hooks
    2. Check for missing dependency arrays in useEffect
    3. Look for performance issues (inline functions, etc.)
    4. Generate a markdown report
    """
    
    async for message in query(prompt=prompt, options=options):
        print(message)

anyio.run(code_analyzer)