Claude Code Agent SDK: The Complete Beginner's Guide to Building AI Agents (2026)

┌─────────────────────────────────────────────────────────────┐
│                    AGENT LOOP PATTERN                       │
├─────────────────────────────────────────────────────────────┤
│  1. GATHER CONTEXT                                          │
│     └─▶ Understand the task, read relevant data             │
│                                                             │
│  2. EXECUTE ACTION                                          │
│     └─▶ Use tools, perform operations                       │
│                                                             │
│  3. CHECK RESULT                                            │
│     └─▶ Was the action successful?                          │
│                                                             │
│  4. REPEAT                                                  │
│     └─▶ Until the goal is achieved                          │
└─────────────────────────────────────────────────────────────┘

# Install with pip
pip install claude-agent-sdk

# Or with uv (recommended for faster installation)
uv pip install claude-agent-sdk

# Set as environment variable
export ANTHROPIC_API_KEY="sk-ant-..."

# Or in a .env file
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def test_connection():
    options = ClaudeAgentOptions(
        model="sonnet",  # Claude Sonnet 4
        system_prompt="You are a helpful assistant."
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Say Hello!")
        async for message in client.receive_response():
            print(message)

# Run
import asyncio
asyncio.run(test_connection())

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock
import asyncio

SYSTEM_PROMPT = """You are a friendly assistant who answers questions.
Be precise and helpful."""

async def simple_qa_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits"  # Allows read operations
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🤖 Q&A Agent ready! (Type 'exit' to quit)\n")
        
        while True:
            user_input = input("You: ").strip()
            
            if user_input.lower() in ['exit', 'quit']:
                print("Goodbye!")
                break
            
            await client.query(user_input)
            
            print("Agent: ", end="")
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="")
            print("\n")

if __name__ == "__main__":
    asyncio.run(simple_qa_agent())

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock
import asyncio

SYSTEM_PROMPT = """You are an assistant with memory.
You remember everything said in this conversation.
Refer to earlier statements when relevant."""

async def memory_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        # The SDK manages conversation history automatically!
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🧠 Memory Agent ready!\n")
        print("Tip: Ask questions that refer to earlier answers.\n")
        
        while True:
            user_input = input("You: ").strip()
            
            if not user_input:
                continue
                
            if user_input.lower() == 'exit':
                break
            
            await client.query(user_input)
            
            print("Agent: ", end="")
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="", flush=True)
            print("\n")

if __name__ == "__main__":
    asyncio.run(memory_agent())

You: My name is Max.
Agent: Hello Max! Nice to meet you.

You: What is my name?
Agent: Your name is Max – you just introduced yourself!

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock, ToolUseBlock
import asyncio

SYSTEM_PROMPT = """You are a research assistant with access to tools.
Use the available tools to complete tasks:

- WebFetch: Retrieves web page content
- Read: Reads local files
- Grep: Searches files for patterns
- Glob: Finds files by patterns

Always explain which tool you're using and why."""

async def tool_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=[
            "WebFetch",  # Fetch web content
            "Read",      # Read files
            "Grep",      # Search text
            "Glob",      # Find files
        ]
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🔧 Tool Agent ready!")
        print("Commands: 'research [URL]', 'find [file]', etc.\n")
        
        while True:
            user_input = input("You: ").strip()
            
            if user_input.lower() == 'exit':
                break
            
            await client.query(user_input)
            
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(f"Agent: {block.text}")
                        elif isinstance(block, ToolUseBlock):
                            print(f"🛠️ Using Tool: {block.name}")
                            print(f"   Parameters: {block.input}")
            print()

if __name__ == "__main__":
    asyncio.run(tool_agent())

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock, ToolUseBlock, ToolResultBlock
import asyncio
import json

TRAVEL_SYSTEM_PROMPT = """You are an autonomous travel planning agent.

YOUR GOAL: Create a complete travel plan based on user requirements.

YOUR WORKFLOW:
1. Gather all necessary information (date, budget, preferences)
2. Research options with WebFetch
3. Create a structured travel plan
4. Present the plan and ask for feedback

IMPORTANT:
- Ask FIRST about missing information
- Use WebFetch for current information
- Create a clear, structured plan
- Offer alternatives

ALWAYS begin with a friendly greeting and ask about the destination."""

async def travel_planner_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=TRAVEL_SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=["WebFetch", "Read", "Write"],
        max_turns=20  # Allows longer agent loops
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("✈️ Travel Planner Agent started!")
        print("=" * 50)
        
        # Initial greeting from the agent
        await client.query("Start travel planning for a new customer.")
        
        async for message in client.receive_response():
            if hasattr(message, 'content'):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Agent: {block.text}")
        print()
        
        # Interactive loop
        while True:
            user_input = input("You: ").strip()
            
            if user_input.lower() in ['exit', 'done', 'thanks']:
                print("Agent: You're welcome! I wish you a wonderful trip! 🌍✨")
                break
            
            await client.query(user_input)
            
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(f"Agent: {block.text}")
                        elif isinstance(block, ToolUseBlock):
                            print(f"🔍 Researching: {block.name}...")
            print()

if __name__ == "__main__":
    asyncio.run(travel_planner_agent())

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# MCP server configuration
MCP_CONFIG = {
    "utils": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://your-mcp-server.com/api"]
    }
}

async def mcp_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt="You have access to MCP tools for extended functionality.",
        permission_mode="acceptEdits",
        allowed_tools=[
            "WebFetch",
            "mcp__utils__save_note",   # MCP tools are prefixed
            "mcp__utils__find_note",
        ],
        mcp_servers=MCP_CONFIG
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Create a note with the title 'Important'")
        # ...

# mcp_server.py - Simple MCP server
from mcp import Server

server = Server("my-tools")

@server.tool(name="save_note")
async def save_note(title: str, content: str) -> dict:
    """Saves a note."""
    # Your logic here
    return {"status": "success", "id": "note_123"}

@server.tool(name="find_note")
async def find_note(pattern: str) -> dict:
    """Finds notes by pattern."""
    # Your logic here
    return {"notes": [...]}

if __name__ == "__main__":
    import asyncio
    asyncio.run(server.run())

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

ORCHESTRATOR_PROMPT = """You are a coordinator who delegates tasks to
specialized subagents:

- Research Agent: For information search
- Writing Agent: For content creation
- Analysis Agent: For data analysis

Delegate tasks according to their type."""

async def orchestrator_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=ORCHESTRATOR_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=["SubAgent", "Read", "Write"],
        subagents_enabled=True  # Enables subagents
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query(
            "Research the latest AI trends and create a report."
        )
        # The agent automatically delegates to subagents

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher

# Define hook function
async def log_tool_usage(event):
    """Logs every tool usage."""
    print(f"📝 Log: Tool '{event.tool_name}' was called")
    return True  # Allows execution

async def block_dangerous_commands(event):
    """Blocks dangerous bash commands."""
    dangerous = ['rm -rf', 'sudo', 'chmod 777']
    if any(cmd in str(event.arguments) for cmd in dangerous):
        print("⚠️ Dangerous command blocked!")
        return False  # Blocks execution
    return True

async def hook_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt="You are an assistant with security hooks.",
        permission_mode="acceptAll",
        allowed_tools=["Bash", "Write", "Read"],
        hooks={
            "PreToolUse": [
                HookMatcher(hooks=[log_tool_usage]),
                HookMatcher(
                    tool_name="Bash",
                    hooks=[block_dangerous_commands]
                )
            ]
        }
    )
    
    async with ClaudeSDKClient(options=options) as client:
        # ...

# ❌ Bad: Vague instructions
SYSTEM_PROMPT = "Be helpful."

# ✅ Good: Clear role, boundaries, and behavior
SYSTEM_PROMPT = """You are a customer service agent for TechCorp.

YOUR ROLE:
- Answer questions about our products
- Forward complex requests to humans
- Document all interactions

BOUNDARIES:
- No price negotiations
- No technical changes without approval
- When uncertain: Ask

BEHAVIOR:
- Friendly and professional
- Answer in the customer's language
- Summarize complex topics"""

# ❌ Bad: Allow everything
permission_mode = "acceptAll"

# ✅ Good: Only allow necessary tools
permission_mode = "acceptEdits"
allowed_tools = ["Read", "WebFetch"]  # Only what's really needed

async def resilient_agent():
    max_retries = 3
    
    for attempt in range(max_retries):
        try:
            async with ClaudeSDKClient(options=options) as client:
                await client.query(prompt)
                async for message in client.receive_response():
                    # Processing
                    pass
                break  # Successful, exit loop
                
        except RateLimitError:
            wait_time = 2 ** attempt  # Exponential backoff
            print(f"Rate limit reached. Waiting {wait_time}s...")
            await asyncio.sleep(wait_time)
            
        except Exception as e:
            print(f"Error: {e}")
            if attempt == max_retries - 1:
                raise

# For long conversations: Compress context
options = ClaudeAgentOptions(
    model="sonnet",
    system_prompt=SYSTEM_PROMPT,
    # SDK automatically compresses when needed
    max_context_tokens=100000,  # Maximum context size
)