Claude Agent SDK

Claude Agent SDK

This skill teaches agents how to create and configure Claude Agent SDK applications with TypeScript or Python, including MCP integration, subagents, permissions, and custom tools.

When to Use

• When creating new Claude Agent SDK applications
• When integrating MCP (Model Context Protocol) servers
• When implementing subagents for specialized tasks
• When configuring permissions and tool access
• When creating custom tools for Claude Code
• When building AI agents with Claude Code capabilities

Core Principles

SDK Overview

Claude Agent SDK allows you to build applications that interact with Claude Code, providing access to:

• Code reading and writing tools
• File system operations
• Custom MCP tools
• Subagents for specialized tasks
• Streaming and single-mode responses
• Permissions and security controls

Official Documentation:

• Overview: https://docs.claude.com/en/api/agent-sdk/overview
• TypeScript: https://docs.claude.com/en/api/agent-sdk/typescript
• Python: https://docs.claude.com/en/api/agent-sdk/python

Project Setup

Language Selection

Supported Languages:

• TypeScript (recommended for Node.js projects)
• Python (recommended for Python ecosystems)

Ask user: "Would you like to use TypeScript or Python?"

Installation

TypeScript:

npm install @anthropic-ai/claude-agent-sdk@latest

Python:

pip install claude-agent-sdk

Always use latest versions - Check npm/PyPI before installing.

Project Initialization

TypeScript Setup:

// package.json
{
  "type": "module",
  "scripts": {
    "start": "node --loader ts-node/esm index.ts",
    "typecheck": "tsc --noEmit"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true
  }
}

Python Setup:

# requirements.txt
claude-agent-sdk>=latest

Environment Configuration

Create .env.example:

ANTHROPIC_API_KEY=your_api_key_here

Add to .gitignore:

.env

Get API Key: https://console.anthropic.com/

Basic Usage

TypeScript Query Pattern

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List all TypeScript files in the project",
  options: {
    allowedTools: ["Glob", "Read"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Python Query Pattern

from claude_agent_sdk import query

async for message in query(
    prompt="List all Python files in the project",
    options={
        "allowedTools": ["Glob", "Read"]
    }
):
    if message["type"] == "result" and message["subtype"] == "success":
        print(message["result"])

MCP Integration

MCP Configuration

Configure MCP servers in .mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

Using MCP Servers in SDK

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List files in my project",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["@modelcontextprotocol/server-filesystem"],
        env: {
          ALLOWED_PATHS: "/Users/me/projects"
        }
      }
    },
    allowedTools: ["mcp__filesystem__list_files"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Python:

from claude_agent_sdk import query

async for message in query(
    prompt="List files in my project",
    options={
        "mcpServers": {
            "filesystem": {
                "command": "python",
                "args": ["-m", "mcp_server_filesystem"],
                "env": {
                    "ALLOWED_PATHS": "/Users/me/projects"
                }
            }
        },
        "allowedTools": ["mcp__filesystem__list_files"]
    }
):
    if message["type"] == "result" and message["subtype"] == "success":
        print(message["result"])

MCP Transport Types

stdio Servers (external processes):

{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": {
        "DEBUG": "${DEBUG:-false}"
      }
    }
  }
}

HTTP/SSE Servers (remote):

{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

SDK MCP Servers (in-process):

• See Custom Tools guide for creating SDK MCP servers
• Use createSdkMcpServer() in TypeScript
• Use create_sdk_mcp_server() in Python

Subagents

Creating Subagents

Programmatic Definition (Recommended):

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review the authentication module for security issues",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Task"], // Task tool required
    agents: {
      "code-reviewer": {
        description: "Expert code review specialist. Use for quality, security, and maintainability reviews.",
        prompt: `You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.`,
        tools: ["Read", "Grep", "Glob"], // Read-only access
        model: "sonnet" // Override default model
      }
    }
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Python:

from claude_agent_sdk import query, AgentDefinition

async for message in query(
    prompt="Review the authentication module for security issues",
    options={
        "allowedTools": ["Read", "Grep", "Glob", "Task"],
        "agents": {
            "code-reviewer": AgentDefinition(
                description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
                prompt="""You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.""",
                tools=["Read", "Grep", "Glob"],
                model="sonnet"
            )
        }
    }
):
    if message["type"] == "result":
        print(message["result"])

Subagent Benefits

Context Management:

• Subagents maintain separate context from main agent
• Prevents information overload
• Keeps interactions focused

Parallelization:

• Multiple subagents can run concurrently
• Dramatically speeds up complex workflows
• Example: Run style-checker, security-scanner, and test-coverage simultaneously

Specialized Instructions:

• Each subagent can have tailored system prompts
• Specific expertise and best practices
• Tool restrictions for safety

Tool Restrictions:

• Limit subagents to specific tools
• Reduce risk of unintended actions
• Example: doc-reviewer with read-only access

Custom Tools (SDK MCP Servers)

Creating Custom Tools

TypeScript:

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

// Define tool with Zod schema
const calculateTool = tool(
  "calculate",
  "Performs mathematical calculations",
  {
    expression: z.string().describe("Mathematical expression to evaluate")
  },
  async (args) => {
    // Execute tool logic
    const result = eval(args.expression); // In production, use a safe evaluator
    return {
      success: true,
      result: result.toString()
    };
  }
);

// Create MCP server with tools
const calculatorServer = createSdkMcpServer({
  name: "calculator",
  version: "1.0.0",
  tools: [calculateTool]
});

// Use in query
for await (const message of query({
  prompt: "Calculate 2 + 2",
  options: {
    mcpServers: {
      "calculator": calculatorServer
    },
    allowedTools: ["mcp__calculator__calculate"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Python:

from claude_agent_sdk import tool, create_sdk_mcp_server, query
from pydantic import BaseModel

# Define tool with Pydantic schema
class CalculateInput(BaseModel):
    expression: str

@tool("calculate", "Performs mathematical calculations", CalculateInput)
async def calculate_handler(args: CalculateInput):
    # Execute tool logic
    result = eval(args.expression)  # In production, use a safe evaluator
    return {"success": True, "result": str(result)}

# Create MCP server with tools
calculator_server = create_sdk_mcp_server(
    name="calculator",
    version="1.0.0",
    tools=[calculate_handler]
)

# Use in query
async for message in query(
    prompt="Calculate 2 + 2",
    options={
        "mcpServers": {
            "calculator": calculator_server
        },
        "allowedTools": ["mcp__calculator__calculate"]
    }
):
    if message["type"] == "result":
        print(message["result"])

Permissions

Permission Modes

Default: "promptUser"

• Claude prompts user before executing actions
• Safest mode for production

Bypass: "bypassPermissions"

• Allows automatic execution without prompts
• Requires allowDangerouslySkipPermissions: true
• Use with caution

Configuration:

options: {
  permissionMode: "promptUser", // or "bypassPermissions"
  allowDangerouslySkipPermissions: false // Required for bypass
}

Streaming vs Single Mode

Streaming Mode (Default)

Real-time responses:

for await (const message of query({
  prompt: "Analyze the codebase",
  options: {
    streaming: true // Default
  }
})) {
  // Handle messages as they arrive
  if (message.type === "text_delta") {
    process.stdout.write(message.text);
  }
}

Single Mode

Complete response:

const result = await query({
  prompt: "List all files",
  options: {
    streaming: false
  }
}).then(async (query) => {
  let fullResult = "";
  for await (const message of query) {
    if (message.type === "result" && message.subtype === "success") {
      fullResult = message.result;
    }
  }
  return fullResult;
});

Error Handling

MCP Connection Failures

Check MCP server status:

for await (const message of query({
  prompt: "Process data",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // Check MCP server status
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );
    
    if (failedServers.length > 0) {
      console.warn("Failed to connect:", failedServers);
    }
  }
  
  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Execution failed:", message.error);
  }
}

Verification

TypeScript Verification

Run type checking:

npx tsc --noEmit

Verify SDK installation:

npm list @anthropic-ai/claude-agent-sdk

Use verification agent: Launch agent-sdk-verifier-ts after setup to validate configuration.

Verification Checklist

SDK Installation:

• ✅ Package installed with latest version
• ✅ package.json has "type": "module" for ES modules
• ✅ Node.js version requirements met

TypeScript Configuration:

• ✅ tsconfig.json exists with proper settings
• ✅ Module resolution supports ES modules
• ✅ Target is modern enough for SDK
• ✅ Type checking passes (tsc --noEmit)

SDK Usage:

• ✅ Correct imports from @anthropic-ai/claude-agent-sdk
• ✅ Agents properly initialized
• ✅ Configuration follows SDK patterns
• ✅ Methods called correctly with proper parameters
• ✅ Streaming vs single mode handled correctly

Environment and Security:

• ✅ .env.example exists with ANTHROPIC_API_KEY
• ✅ .env is in .gitignore
• ✅ API keys not hardcoded in source files
• ✅ Proper error handling around API calls

Best Practices

✅ DO

• Always use latest SDK versions (check npm/PyPI before installing)
• Use TypeScript for type safety and better IDE support
• Verify code runs correctly before finishing (tsc --noEmit for TypeScript)
• Use .env for API keys, never hardcode
• Write clear subagent descriptions for automatic invocation
• Use tool restrictions for subagents to reduce risk
• Handle MCP connection failures gracefully
• Use streaming mode for real-time feedback
• Test with verification agents after setup

❌ DON'T

• Don't skip version checking (always use latest versions)
• Don't hardcode API keys in source files
• Don't forget to add .env to .gitignore
• Don't skip type checking (fix all errors before finishing)
• Don't use bypassPermissions without understanding risks
• Don't forget to include Task tool when using subagents
• Don't ignore MCP connection errors
• Don't skip verification after setup

Common Patterns

Code Review Agent

Use case: Automated code review with security focus

agents: {
  "code-reviewer": {
    description: "Expert code review specialist. Use for quality, security, and maintainability reviews.",
    prompt: `You are a code review specialist focusing on:
- Security vulnerabilities
- Performance issues
- Code quality and maintainability
- Best practices adherence`,
    tools: ["Read", "Grep", "Glob"], // Read-only
    model: "sonnet"
  }
}

Test Runner Agent

Use case: Run tests and report results

agents: {
  "test-runner": {
    description: "Runs test suites and reports results. Use for automated testing.",
    prompt: `You are a test execution specialist. Run tests and report:
- Test results (pass/fail)
- Coverage metrics
- Performance benchmarks
- Error details`,
    tools: ["Bash"], // Can execute commands
    model: "sonnet"
  }
}

Research Assistant Agent

Use case: Explore documentation and codebase

agents: {
  "research-assistant": {
    description: "Research specialist. Use for exploring codebases and documentation.",
    prompt: `You are a research assistant. Explore and analyze:
- Codebase structure
- Documentation
- API references
- Implementation patterns`,
    tools: ["Read", "Grep", "Glob", "WebFetch"], // Read and fetch
    model: "sonnet"
  }
}

Reference

• Official Docs:

  • Overview: https://docs.claude.com/en/api/agent-sdk/overview
  • TypeScript: https://docs.claude.com/en/api/agent-sdk/typescript
  • Python: https://docs.claude.com/en/api/agent-sdk/python
  • MCP Integration: https://docs.claude.com/en/api/agent-sdk/mcp
  • Subagents: https://docs.claude.com/en/api/agent-sdk/subagents
  • Custom Tools: https://docs.claude.com/en/api/agent-sdk/custom-tools

• Project Files:

  • claude-reference/skills/sdk-agent-new.md - Creating new SDK applications
  • claude-reference/skills/sdk-verifier.md - Verification patterns
  • claude-reference/agents/mcp.md - MCP integration details

• Related Rules:

  • .cursor/rules/agent-skills.mdc - Agent Skills pattern
  • .cursor/rules/subagents.mdc - Subagents pattern

Created: 2025-01-16
Based on: Claude Agent SDK documentation and best practices
Version: 1.0.0