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

pip install claude-agent-sdk

// 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
  }
}

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

ANTHROPIC_API_KEY=your_api_key_here

.env

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);
  }
}

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"])

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

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);
  }
}

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"])

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

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

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);
  }
}

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"])

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);
  }
}

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"])

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

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);
  }
}

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;
});

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);
  }
}

npx tsc --noEmit

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

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"
  }
}

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"
  }
}

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"
  }
}