Claude Agent SDK

Status: Production Ready Last Updated: 2025-10-25 Dependencies: @anthropic-ai/claude-agent-sdk, zod Latest Versions: @anthropic-ai/claude-agent-sdk@0.1.0+, zod@3.23.0+

Quick Start (5 Minutes)

1. Install SDK

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

Why these packages:

• @anthropic-ai/claude-agent-sdk - Main Agent SDK
• zod - Type-safe schema validation for tools

2. Set API Key

export ANTHROPIC_API_KEY="sk-ant-..."

CRITICAL:

• API key required for all agent operations
• Never commit API keys to version control
• Use environment variables

3. Basic Query

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

const response = query({
  prompt: "Analyze the codebase and suggest improvements",
  options: {
    model: "claude-sonnet-4-5",
    workingDirectory: process.cwd(),
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

for await (const message of response) {
  if (message.type === 'assistant') {
    console.log(message.content);
  }
}

The Complete Claude Agent SDK Reference

Table of Contents

1. Core Query API
2. Tool Integration
3. MCP Servers
4. Subagent Orchestration
5. Session Management
6. Permission Control
7. Filesystem Settings
8. Message Types & Streaming
9. Error Handling
10. Known Issues

Core Query API

The query() Function

The primary interface for interacting with Claude Code CLI programmatically.

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

const response = query({
  prompt: string | AsyncIterable<SDKUserMessage>,
  options?: Options
});

// Response is AsyncGenerator<SDKMessage, void>
for await (const message of response) {
  // Process streaming messages
}

Basic Options

const response = query({
  prompt: "Review this code for bugs",
  options: {
    model: "claude-sonnet-4-5",        // or "haiku", "opus"
    workingDirectory: "/path/to/project",
    systemPrompt: "You are a security-focused code reviewer.",
    allowedTools: ["Read", "Grep", "Glob"],
    disallowedTools: ["Write", "Edit", "Bash"],
    permissionMode: "default"           // or "acceptEdits", "bypassPermissions"
  }
});

Model Selection

Default: "sonnet" if not specified

System Prompts

const response = query({
  prompt: "Implement user authentication",
  options: {
    systemPrompt: `You are an expert backend developer.

Follow these principles:
- Always use TypeScript with strict types
- Implement comprehensive error handling
- Add detailed logging for debugging
- Write unit tests for all functions
- Follow OWASP security guidelines`
  }
});

CRITICAL:

• System prompt sets agent behavior for entire session
• Should be clear and specific
• Can be 1-10k tokens (affects context window)

Working Directory

const response = query({
  prompt: "Refactor the user service",
  options: {
    workingDirectory: "/Users/dev/projects/my-app",
    // Agent operates within this directory
    // Relative paths resolved from here
  }
});

Best Practices:

• Use absolute paths for clarity
• Agent stays within this directory scope
• Critical for multi-project environments

Tool Integration (Built-in + Custom)

Built-in Tools

The SDK provides access to Claude Code's built-in tools:

Allowing/Disallowing Tools

// Whitelist approach (recommended)
const response = query({
  prompt: "Analyze code but don't modify anything",
  options: {
    allowedTools: ["Read", "Grep", "Glob"]
    // ONLY these tools can be used
  }
});

// Blacklist approach
const response = query({
  prompt: "Review and fix issues",
  options: {
    disallowedTools: ["Bash"]
    // Everything except Bash allowed
  }
});

// Combination (allowedTools takes precedence)
const response = query({
  prompt: "Safe code review",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Edit"],
    disallowedTools: ["Edit"]  // Edit still blocked (allowedTools overridden)
  }
});

CRITICAL:

• allowedTools = whitelist (only these tools)
• disallowedTools = blacklist (everything except these)
• If both specified, allowedTools wins

Custom Tool Execution Monitoring

const response = query({
  prompt: "Implement feature X",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Bash"]
  }
});

for await (const message of response) {
  if (message.type === 'tool_call') {
    console.log(`Tool requested: ${message.tool_name}`);
    console.log(`Input:`, message.input);
  } else if (message.type === 'tool_result') {
    console.log(`Tool ${message.tool_name} completed`);
  }
}

MCP Servers (Model Context Protocol)

Overview

MCP servers extend agent capabilities with custom tools. The SDK supports:

• In-process servers (createSdkMcpServer) - Run in same process
• External servers (stdio, HTTP, SSE) - Separate processes

Creating In-Process MCP Servers

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

const weatherServer = createSdkMcpServer({
  name: "weather-service",
  version: "1.0.0",
  tools: [
    tool(
      "get_weather",
      "Get current weather for a location",
      {
        location: z.string().describe("City name or coordinates"),
        units: z.enum(["celsius", "fahrenheit"]).default("celsius")
      },
      async (args) => {
        // Tool implementation
        const response = await fetch(
          `https://api.weather.com/v1/current?location=${args.location}&units=${args.units}`
        );
        const data = await response.json();

        return {
          content: [{
            type: "text",
            text: `Temperature: ${data.temp}° ${args.units}
Conditions: ${data.conditions}
Humidity: ${data.humidity}%`
          }]
        };
      }
    )
  ]
});

// Use in query
const response = query({
  prompt: "What's the weather in San Francisco?",
  options: {
    mcpServers: {
      "weather-service": weatherServer
    },
    allowedTools: ["mcp__weather-service__get_weather"]
  }
});

Tool Definition Pattern

tool(
  name: string,                    // Tool identifier
  description: string,             // What the tool does
  inputSchema: ZodSchema,          // Input validation
  handler: async (args) => Result // Implementation
)

Input Schema Options:

// Simple object schema
{
  email: z.string().email(),
  limit: z.number().min(1).max(100).default(10),
  enabled: z.boolean().optional()
}

// Complex nested schema
{
  user: z.object({
    name: z.string(),
    age: z.number().min(0)
  }),
  filters: z.array(z.string()).optional()
}

// Enum types
{
  status: z.enum(["pending", "active", "completed"]),
  pr