claude-agent-sdk

What this skill does

# Claude Agent SDK - Comprehensive Skill

## Overview

The **Claude Agent SDK** is Anthropic's official framework for building production-ready AI agents with Claude. It provides a high-level abstraction over the Messages API, handling the agent loop, tool orchestration, context management, and extended-thinking patterns automatically.

### When to Use the Agent SDK

**Use the Agent SDK when:**

- Building autonomous agents that need to use tools iteratively
- Implementing agentic workflows with verification and iteration
- Creating subagent hierarchies for complex task decomposition
- Integrating MCP (Model Context Protocol) servers for standardized tools
- Need production patterns like hooks, permissions, and context management

**Don't use when:**

- Simple single-turn API calls suffice (use Messages API directly)
- No tool use required (standard chat)
- Custom agent loop logic needed (SDK loop is opinionated)

### Language Support

- **Python**: `claude-agents` package (recommended for most use cases)
- **TypeScript**: `@anthropics/agent-sdk` package (Node.js environments)

Both implementations share the same core concepts and API patterns.

## Quick Start

### Installation

**Python:**

```bash
pip install claude-agents
```

**TypeScript:**

```bash
npm install @anthropics/agent-sdk
```

### Authentication

Set your API key as an environment variable:

```bash
export ANTHROPIC_API_KEY="your-api-key-here"  # pragma: allowlist secret
```

Or pass it explicitly in code:

```python
from claude_agents import Agent

agent = Agent(api_key="your-api-key-here")
```

### Basic Agent Creation

**Python Example:**

```python
from claude_agents import Agent

# Create agent with default settings
agent = Agent(
    model="claude-sonnet-4-5-20250929",
    system="You are a helpful assistant focused on accuracy."
)

# Run simple task
result = agent.run("What is 2+2?")
print(result.response)
```

**TypeScript Example:**

```typescript
import { Agent } from "@anthropics/agent-sdk";

const agent = new Agent({
  model: "claude-sonnet-4-5-20250929",
  system: "You are a helpful assistant focused on accuracy.",
});

const result = await agent.run("What is 2+2?");
console.log(result.response);
```

### First Tool Example

Tools extend agent capabilities with external functions:

**Python:**

```python
from claude_agents import Agent
from claude_agents.tools import Tool

# Define custom tool
def get_weather(location: str) -> dict:
    """Get weather for a location."""
    return {"location": location, "temp": 72, "condition": "sunny"}

weather_tool = Tool(
    name="get_weather",
    description="Get current weather for a location",
    input_schema={
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City name"}
        },
        "required": ["location"]
    },
    function=get_weather
)

# Agent with custom tool
agent = Agent(
    model="claude-sonnet-4-5-20250929",
    tools=[weather_tool]
)

result = agent.run("What's the weather in San Francisco?")
print(result.response)
```

## Core Concepts Reference

### The Agent Loop

The SDK manages a complete agent loop automatically:

1. **Input Processing**: User message + system prompt + tools
2. **Model Invocation**: Claude generates response (text or tool calls)
3. **Tool Execution**: SDK executes requested tools, handles results
4. **Iteration**: Results fed back to model, continues until completion
5. **Output**: Final response with full conversation history

**Key Properties:**

- Automatic iteration until task completion or max turns
- Built-in error handling and retry logic
- Context management with automatic compaction options
- Token budget tracking and optimization

### Context Management

The SDK manages conversation context automatically:

**Context Components:**

- System prompt (persistent instructions)
- Conversation history (user messages + assistant responses)
- Tool definitions (available capabilities)
- Tool results (execution outputs)

**Subagents for Context Isolation:**

```python
# Spawn subagent with isolated context
with agent.subagent(
    system="You are a code reviewer focused on security.",
    tools=[security_scan_tool]
) as reviewer:
    review = reviewer.run("Review this code for vulnerabilities: ...")

# Subagent context doesn't pollute parent
```

**Context Compaction:**
When approaching token limits, the SDK can automatically summarize earlier conversation turns while preserving critical information.

### Tools System

Tools are the agent's interface to external capabilities.

**Built-in Tools:**

- `bash`: Execute shell commands
- `read_file`: Read file contents
- `write_file`: Write data to files
- `edit_file`: Modify existing files
- `glob`: File pattern matching
- `grep`: Content search

**Custom Tool Schema:**

```python
Tool(
    name="tool_name",              # Unique identifier
    description="What it does",    # Clear capability description
    input_schema={                 # JSON Schema for parameters
        "type": "object",
        "properties": {...},
        "required": [...]
    },
    function=callable              # Python function or async function
)
```

**MCP Integration:**
The SDK can use Model Context Protocol (MCP) servers as tool providers:

```python
from claude_agents import Agent
from claude_agents.mcp import MCPClient

# Connect to MCP server
mcp_client = MCPClient("npx", ["-y", "@modelcontextprotocol/server-filesystem"])

agent = Agent(
    model="claude-sonnet-4-5-20250929",
    mcp_clients=[mcp_client]
)
```

### Permissions System

Control which tools agents can access:

**Allowed Tools (Whitelist):**

```python
agent = Agent(
    model="claude-sonnet-4-5-20250929",
    tools=[tool1, tool2, tool3, tool4],
    allowed_tools=["tool1", "tool2"]  # Only these can be used
)
```

**Disallowed Tools (Blacklist):**

```python
agent = Agent(
    model="claude-sonnet-4-5-20250929",
    tools=[tool1, tool2, tool3],
    disallowed_tools=["tool3"]  # All except tool3
)
```

**Permission Modes:**

- `"strict"`: Agent MUST get permission before tool use (via hooks)
- `"permissive"`: Agent can use allowed tools freely (default)

### Hooks System

Hooks provide lifecycle event interception for observability, validation, and control.

**Available Hooks:**

- `PreToolUseHook`: Before tool execution (validation, logging, blocking)
- `PostToolUseHook`: After tool execution (logging, result modification)
- `PreSubagentStartHook`: Before subagent spawns (context setup)
- `PostSubagentStopHook`: After subagent completes (result processing)

**Basic Hook Example:**

```python
from claude_agents.hooks import PreToolUseHook

class LoggingHook(PreToolUseHook):
    async def execute(self, context):
        print(f"Tool: {context.tool_name}")
        print(f"Args: {context.tool_input}")
        return context  # Allow execution

agent = Agent(
    model="claude-sonnet-4-5-20250929",
    hooks=[LoggingHook()]
)
```

**Blocking Tool Use:**

```python
class ValidationHook(PreToolUseHook):
    async def execute(self, context):
        if context.tool_name == "bash" and "rm -rf" in context.tool_input.get("command", ""):
            raise PermissionError("Destructive command blocked")
        return context
```

## Common Patterns

### File Operations

```python
from claude_agents import Agent

agent = Agent(
    model="claude-sonnet-4-5-20250929",
    allowed_tools=["read_file", "write_file", "glob"]
)

result = agent.run(
    "Read all Python files in ./src and create a summary in summary.md"
)
```

### Code Execution

```python
agent = Agent(
    model="claude-sonnet-4-5-20250929",
    allowed_tools=["bash"]
)

result = agent.run(
    "Run the test suite and analyze any failures"
)
```

### Agentic Search (Gather-Act Pattern)

```python
# Agent automatically gathers information iteratively
search_agent = Agent(
    model="claude-sonnet-4-5-20250929",
    tools=[web_search_tool, read_url_tool]
)

result = search_agent.run(