Claude Agent SDK

Overview

Claude Agent SDK is Anthropic's agent development framework, built around Claude's unique capabilities such as extended thinking, the tool_use protocol, and MCP integration. This article provides an in-depth introduction to its architecture and usage.

Core Architecture

graph TD
    subgraph Claude Agent SDK
        A[Agent] --> B[System Prompt]
        A --> C[Tools<br/>Tool Definitions]
        A --> D[MCP Servers]
        A --> E[Model Config]
    end

    subgraph Tool Use Protocol
        C --> C1[function<br/>Custom Functions]
        C --> C2[computer_use<br/>Computer Operations]
        C --> C3[text_editor<br/>Text Editing]
        C --> C4[bash<br/>Command Line]
    end

    subgraph MCP Integration
        D --> D1[File System]
        D --> D2[Database]
        D --> D3[API Gateway]
        D --> D4[Custom Server]
    end

    subgraph Execution
        F[Agent Loop] --> G[Message]
        G --> H{Response Type}
        H -->|text| I[Text Output]
        H -->|tool_use| J[Execute Tool]
        J --> G
        H -->|end_turn| K[Complete]
    end

tool_use Protocol

Claude's tool_use is a structured tool calling protocol, more standardized than simple function calling.

Tool Definition

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get current weather information for a location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City name, e.g., 'San Francisco, CA'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Temperature unit"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "search_database",
        "description": "Search the product database.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "limit": {"type": "integer", "default": 10}
            },
            "required": ["query"]
        }
    }
]

Agent Loop Implementation

def run_agent_loop(system_prompt, user_message, tools, max_turns=10):
    """Core loop of the Claude Agent"""
    messages = [{"role": "user", "content": user_message}]

    for turn in range(max_turns):
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=4096,
            system=system_prompt,
            tools=tools,
            messages=messages,
        )

        if response.stop_reason == "end_turn":
            text_blocks = [b.text for b in response.content if b.type == "text"]
            return "\n".join(text_blocks)

        if response.stop_reason == "tool_use":
            messages.append({"role": "assistant", "content": response.content})

            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": str(result)
                    })

            messages.append({"role": "user", "content": tool_results})

    return "Max turns reached"

Extended Thinking

Claude's Extended Thinking feature lets the model engage in deep thinking before responding, particularly useful for complex agent tasks.

Enabling Extended Thinking

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000  # Thinking token budget
    },
    messages=[{
        "role": "user", 
        "content": "Analyze this complex system architecture and suggest improvements..."
    }]
)

for block in response.content:
    if block.type == "thinking":
        print(f"[Thinking]: {block.thinking}")
    elif block.type == "text":
        print(f"[Response]: {block.text}")

MCP Integration

Model Context Protocol (MCP) is Anthropic's open standard for connecting LLMs with external data sources and tools.

MCP Server Connection

from anthropic import Anthropic
from anthropic.types import MCPServerConfig

mcp_servers = [
    MCPServerConfig(
        name="filesystem",
        command="npx",
        args=["-y", "@anthropic/mcp-server-filesystem", "/path/to/workspace"]
    ),
    MCPServerConfig(
        name="database",
        command="npx",
        args=["-y", "@anthropic/mcp-server-postgres", "postgresql://..."]
    ),
]

agent = Agent(
    model="claude-sonnet-4-20250514",
    mcp_servers=mcp_servers,
    system_prompt="You have access to filesystem and database tools."
)

MCP Tool Protocol

graph LR
    A[Claude Agent] -->|tool_use request| B[MCP Client]
    B -->|JSON-RPC| C[MCP Server]
    C -->|Execute| D[External Resource<br/>Files / Database / API]
    D -->|Result| C
    C -->|JSON-RPC response| B
    B -->|tool_result| A

MCP advantages:

Standardization: Unified tool connection protocol
Discoverability: Agents automatically discover available tools
Security: Built-in permission controls
Reusability: MCP servers can be reused across agents

Claude Code Internal Mechanisms

Claude Code is a CLI tool built on the Claude Agent SDK, demonstrating real-world application of the Agent SDK.

How It Works

graph TD
    A[User Input] --> B[System Prompt<br/>with Project Context]
    B --> C[Claude Agent Loop]
    C --> D{Need Tools?}
    D -->|Yes| E[Tool Execution]
    E --> E1[Read File]
    E --> E2[Edit File]
    E --> E3[Bash Command]
    E --> E4[Search/Grep]
    E1 --> C
    E2 --> C
    E3 --> C
    E4 --> C
    D -->|No| F[Output Response]

Core Design Patterns

Project context injection: CLAUDE.md files provide project-specific instructions
Multi-tool coordination: Coordination of file I/O, search, and command execution
Permission model: User confirmation for high-risk operations
Session management: Context preservation across multi-turn conversations

Comparison with Other SDKs

Feature	Claude Agent SDK	OpenAI Agents SDK	LangChain
Model support	Claude series	GPT series	Multiple
Tool protocol	tool_use + MCP	function calling	Multiple adapters
Extended Thinking	Native support	Not supported	Not supported
Multi-agent	Manual implementation	Handoff native	LangGraph
Observability	Logging	Trace	LangSmith
Computer Use	Native support	Not supported	Not supported

Best Practices

1. Prompt Engineering

system_prompt = """You are a specialized agent for {domain}.

## Capabilities
You have access to the following tools:
{tool_descriptions}

## Guidelines
1. Always verify before making changes
2. Explain your reasoning before acting
3. Handle errors gracefully

## Constraints
- Never execute destructive operations without confirmation
- Stay within the scope of your role
"""

2. Error Handling

def safe_tool_execution(tool_name, tool_input):
    try:
        result = tool_map[tool_name](**tool_input)
        return {"status": "success", "result": result}
    except PermissionError:
        return {"status": "error", "message": "Permission denied"}
    except TimeoutError:
        return {"status": "error", "message": "Operation timed out"}
    except Exception as e:
        return {"status": "error", "message": str(e)}

3. Cost Optimization

Use claude-haiku for simple routing and classification tasks
Use claude-sonnet for most agent tasks
Use claude-opus or extended thinking only when deep reasoning is needed
Set thinking.budget_tokens appropriately

Summary

Core features of the Claude Agent SDK:

tool_use protocol: Structured, reliable tool calling
MCP integration: Standardized external resource connections
Extended Thinking: Deep reasoning for complex tasks
Computer Use: Unique GUI operation capability
Safety-first design: Built-in security considerations and permission model