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"

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:

Input Processing: User message + system prompt + tools
Model Invocation: Claude generates response (text or tool calls)
Tool Execution: SDK executes requested tools, handles results
Iteration: Results fed back to model, continues until completion
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(
    "Research the latest developments in quantum computing and summarize key papers"
)

Subagent Delegation

python

main_agent = Agent(model="claude-sonnet-4-5-20250929")

# Delegate specialized task to subagent
with main_agent.subagent(
    system="You are an expert data analyzer.",
    tools=[analyze_csv_tool, plot_tool]
) as analyzer:
    analysis = analyzer.run("Analyze sales_data.csv and create visualizations")

# Results available to main agent
main_agent.run(f"Based on this analysis: {analysis.response}, what actions should we take?")

Error Handling

python

from claude_agents import Agent, AgentError

agent = Agent(model="claude-sonnet-4-5-20250929")

try:
    result = agent.run("Your task here", max_turns=10)
except AgentError as e:
    print(f"Agent failed: {e}")
    print(f"Turns completed: {e.turns_completed}")
    print(f"Last message: {e.last_message}")

Verification Pattern

python

# Agent can self-verify results
agent = Agent(
    model="claude-sonnet-4-5-20250929",
    tools=[calculator_tool, verify_tool]
)

result = agent.run(
    "Calculate the compound interest for $10000 at 5% for 10 years. "
    "Verify your calculation by computing it a second way."
)

Navigation Guide

When to Read Supporting Files

reference.md - Read when you need:

Deep understanding of agent loop internals
Complete API reference for all SDK features
Detailed tool schema specifications
Permission and security configuration options
Comprehensive hooks reference with all event types
Skills system implementation details

examples.md - Read when you need:

Working code examples for specific patterns
Tool implementation templates
Hook implementation examples
Advanced patterns (subagents, verification, error recovery)
Integration examples with existing systems

patterns.md - Read when you need:

Production-ready architectural patterns
Agent loop optimization strategies (Gather, Act, Verify, Iterate)
Context management best practices
Tool design principles
Security patterns and anti-patterns
Performance optimization techniques

drift-detection.md - Read when you need:

Understanding how this skill stays current
Implementing drift detection for other skills
Update workflow and validation processes
Self-validation mechanisms

Integration with Amplihack

The Agent SDK skill integrates with the Amplihack framework:

Creating Amplihack Agents with SDK:

python

# In .claude/agents/amplihack/specialized/my_agent.md
# Use Agent SDK patterns for tool-using agents
from claude_agents import Agent
from claude_agents.tools import Tool

def create_specialized_agent():
    return Agent(
        model="claude-sonnet-4-5-20250929",
        system="<agent_role_from_md>",
        tools=[...],  # Custom tools for this agent
        hooks=[...]   # Logging, validation hooks
    )

Using MCP Servers in Amplihack:

python

# Integrate MCP tools into Amplihack workflow
from claude_agents.mcp import MCPClient

mcp_client = MCPClient("npx", ["-y", "@modelcontextprotocol/server-github"])

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

# Agent can now use GitHub MCP tools
result = agent.run("Create a GitHub issue for the bug we just found")

Hooks for Amplihack Observability:

python

# Log all agent actions to Amplihack runtime logs
class AmplihackLoggingHook(PreToolUseHook):
    async def execute(self, context):
        log_to_amplihack_runtime(
            session_id=get_current_session(),
            tool=context.tool_name,
            input=context.tool_input
        )
        return context

Quick Reference

Essential Commands

python

# Basic agent
agent = Agent(model="claude-sonnet-4-5-20250929")
result = agent.run("task")

# With tools
agent = Agent(model="...", tools=[tool1, tool2])

# With permissions
agent = Agent(model="...", allowed_tools=["tool1"])

# With hooks
agent = Agent(model="...", hooks=[LogHook()])

# Subagent
with agent.subagent(system="...") as sub:
    result = sub.run("subtask")

# MCP integration
from claude_agents.mcp import MCPClient
mcp = MCPClient("npx", ["-y", "mcp-server-name"])
agent = Agent(model="...", mcp_clients=[mcp])

Common Tool Patterns

python

# File operations
tools=["read_file", "write_file", "glob"]

# Code execution
tools=["bash"]

# All built-in
tools=["bash", "read_file", "write_file", "edit_file", "glob", "grep"]

Token Budget Recommendations

Simple tasks: 4K-8K tokens
Complex tasks: 16K-32K tokens
Research/analysis: 64K-128K tokens
Maximum context: 200K tokens (model dependent)

Next Steps

Start Simple: Create a basic agent with built-in tools
Add Custom Tools: Implement tools for your specific domain
Add Hooks: Implement logging and validation
Use Subagents: Delegate specialized tasks
Integrate MCP: Use standardized tool servers
Optimize: Tune context, permissions, and verification patterns

For complete API details, see

reference.md

. For working code, see

examples.md

. For production patterns, see

patterns.md

agent-sdk

NPX Install

Tags

SKILL.md Content

Claude Agent SDK - Comprehensive Skill

Overview

When to Use the Agent SDK

Language Support

Quick Start

Installation

Authentication

Basic Agent Creation

First Tool Example

Core Concepts Reference

The Agent Loop

Context Management

Tools System

Permissions System

Hooks System

Common Patterns

File Operations

Code Execution

Agentic Search (Gather-Act Pattern)

Subagent Delegation

Error Handling

Verification Pattern

Navigation Guide

When to Read Supporting Files

Integration with Amplihack

Quick Reference

Essential Commands

Common Tool Patterns

Token Budget Recommendations

Next Steps