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:

pip install claude-agents

TypeScript:

npm install @anthropics/agent-sdk

Authentication

Set your API key as an environment variable:

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

Or pass it explicitly in code:

from claude_agents import Agent

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

Basic Agent Creation

Python Example:

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:

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:

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:

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:

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:

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):

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):

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:

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:

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

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

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)

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

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

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

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:

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:

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:

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

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

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 .