The Complete Guide to Claude Code Agent SDK: Build Your Own AI Agents with Claude's Engine

npm install @anthropic-ai/claude-code

pip install claude-code-sdk

import { query, type Message } from "@anthropic-ai/claude-code";
 
const messages: Message[] = [];
 
for await (const message of query({
  prompt: "Explain what an Agent Loop is",
  options: {
    maxTurns: 3,
  },
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  }
  messages.push(message);
}

from claude_code_sdk import query, ClaudeCodeOptions, Message
 
messages: list[Message] = []
 
async for message in query(
    prompt="Explain what an Agent Loop is",
    options=ClaudeCodeOptions(max_turns=3),
):
    if message.type == "assistant":
        for block in message.message.content:
            if hasattr(block, "text"):
                print(block.text, end="")
    messages.append(message)

query({
  prompt: string,           // User input
  options: {
    model?: string,         // Model, defaults to claude-sonnet-4-20250514
    systemPrompt?: string,  // Fully replace default system prompt
    appendSystemPrompt?: string, // Append to default system prompt
    allowedTools?: string[], // Tool allowlist
    disallowedTools?: string[], // Tool blocklist
    permissionMode?: string, // Permission mode
    cwd?: string,           // Working directory
    mcpServers?: Record<string, McpServerConfig>, // MCP servers
    maxTurns?: number,      // Maximum turns
  },
})

// Only allow reading and searching, no write operations
options: {
  allowedTools: ["Read", "Glob", "Grep"],
}

type Message =
  | { type: "assistant"; message: AssistantMessage }  // Claude's response
  | { type: "user"; message: UserMessage }            // Tool results (auto-generated)
  | { type: "result"; result: ResultMessage }          // Final result

import { query, type Message } from "@anthropic-ai/claude-code";
 
// First turn
const history: Message[] = [];
for await (const msg of query({ prompt: "Read package.json" })) {
  history.push(msg);
}
 
// Second turn, with history
for await (const msg of query({
  prompt: "Change the name field to my-app",
  options: { messages: history },
})) {
  history.push(msg);
}

import { createSession } from "@anthropic-ai/claude-code";
 
const session = await createSession({
  model: "claude-sonnet-4-20250514",
  systemPrompt: "You are a code review assistant",
});
 
// Multi-turn conversation, session manages context automatically
const response1 = await session.send("Analyze the security of src/auth.ts");
const response2 = await session.send("Suggest fixes for the issues found");
 
// Streaming output
for await (const chunk of session.stream("Summarize all findings")) {
  process.stdout.write(chunk);
}

// Code review agent: read-only, cannot modify anything
const reviewAgent = query({
  prompt: "Review the code quality of this PR",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Bash(git diff)"],
    permissionMode: "plan",
  },
});
 
// Documentation agent: can read code, write Markdown
const docAgent = query({
  prompt: "Generate API docs for the src/api/ directory",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Write", "Edit"],
    permissionMode: "autoEdit",
  },
});

allowedTools: [
  "Bash(npm test)",      // Only allow running tests
  "Bash(git diff)",      // Only allow viewing diffs
  "Bash(git log)",       // Only allow viewing logs
]

// Recommended production configuration
query({
  prompt: userInput,
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "plan",
    maxTurns: 10,
    cwd: "/app/workspace",
  },
});

query({
  prompt: "Check recent GitHub Issues",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN,
        },
      },
    },
  },
});

import { query } from "@anthropic-ai/claude-code";
 
async function dbQueryAgent(question: string) {
  const messages = [];
 
  for await (const message of query({
    prompt: question,
    options: {
      appendSystemPrompt:
        "You are a database analysis assistant. Users will ask questions about data. " +
        "Use MCP tools to query the PostgreSQL database. " +
        "Always check table structure before querying. Avoid full table scans.",
      mcpServers: {
        postgres: {
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-postgres"],
          env: {
            POSTGRES_CONNECTION_STRING: process.env.DATABASE_URL,
          },
        },
      },
      allowedTools: [
        "mcp__postgres__query",
        "mcp__postgres__list_tables",
        "mcp__postgres__describe_table",
      ],
      maxTurns: 10,
    },
  })) {
    messages.push(message);
  }
 
  const result = messages.find((m) => m.type === "result");
  return result?.result;
}
 
// Usage
const answer = await dbQueryAgent("How many new users last month? Break down by week.");

import { query, type Message } from "@anthropic-ai/claude-code";
 
interface ReviewResult {
  summary: string;
  issues: Array<{
    severity: "error" | "warning" | "info";
    file: string;
    line?: number;
    message: string;
  }>;
}
 
async function codeReviewAgent(baseBranch = "main"): Promise<ReviewResult> {
  const messages: Message[] = [];
 
  for await (const message of query({
    prompt: `Review all code changes on the current branch relative to ${baseBranch}.
 
Requirements:
1. Run git diff ${baseBranch}...HEAD to see changes
2. Analyze file by file, focusing on: security vulnerabilities, performance issues, logic errors, code style
3. Output results as JSON in this format:
{
  "summary": "Overall assessment",
  "issues": [
    { "severity": "error|warning|info", "file": "path", "line": lineNumber, "message": "description" }
  ]
}
Output only JSON, nothing else.`,
    options: {
      allowedTools: ["Bash(git diff)", "Bash(git log)", "Read", "Glob", "Grep"],
      permissionMode: "plan",
      maxTurns: 15,
    },
  })) {
    messages.push(message);
  }
 
  const result = messages.find((m) => m.type === "result");
  return JSON.parse(result?.result?.text ?? "{}");
}

import { query, type Message } from "@anthropic-ai/claude-code";
 
async function generateApiDocs(sourceDir: string, outputFile: string) {
  const messages: Message[] = [];
 
  for await (const message of query({
    prompt: `Generate API documentation for all TypeScript files in ${sourceDir}.
 
Steps:
1. Use Glob to find all .ts files
2. Read each file, extract exported functions, classes, and interfaces
3. Generate docs for each export: description, parameters, return values, usage examples
4. Write the complete documentation to ${outputFile} in Markdown format`,
    options: {
      allowedTools: ["Read", "Glob", "Grep", "Write"],
      permissionMode: "autoEdit",
      maxTurns: 30,
    },
  })) {
    messages.push(message);
  }
 
  console.log(`Documentation generated: ${outputFile}`);
}
 
// Usage
await generateApiDocs("src/api", "docs/API.md");

query({
  prompt: "Refactor src/utils.ts",
  options: {
    hooks: {
      preToolUse: [
        {
          matcher: "Write|Edit",
          command: "echo 'File modification detected' >> /tmp/agent.log",
        },
      ],
      postToolUse: [
        {
          matcher: "Bash",
          command: "echo 'Command executed' >> /tmp/agent.log",
        },
      ],
    },
  },
});

query({
  prompt: `Complete the following tasks:
1. Review the security of src/auth/
2. Review the API design of src/api/
3. Summarize both reviews
 
Use sub-agents to handle the first two tasks in parallel, then summarize.`,
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Agent"],
    maxTurns: 20,
  },
});

const controller = new AbortController();
 
// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);
 
try {
  for await (const message of query({
    prompt: "Analyze the entire codebase architecture",
    options: { signal: controller.signal },
  })) {
    // Process messages...
  }
} catch (err) {
  if (err.name === "AbortError") {
    console.log("Task cancelled");
  }
}

// ci-review.ts — Auto-run code review on PRs
import { query } from "@anthropic-ai/claude-code";
 
async function ciReview() {
  const messages = [];
 
  for await (const msg of query({
    prompt: "Review the current PR's code changes, output a Markdown review report",
    options: {
      allowedTools: [
        "Bash(git diff)",
        "Bash(git log)",
        "Read",
        "Glob",
        "Grep",
      ],
      permissionMode: "plan", // Read-only, no file modifications
      maxTurns: 15,
    },
  })) {
    messages.push(msg);
  }
 
  const result = messages.find((m) => m.type === "result");
  return result?.result?.text ?? "Review complete, no issues found.";
}

# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]
 
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm install @anthropic-ai/claude-code
      - run: npx tsx ci-review.ts
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

# Install CLI first
npm install -g @anthropic-ai/claude-code
 
# Then install SDK
npm install @anthropic-ai/claude-code

query({
  prompt: "...",
  options: {
    model: "claude-opus-4-20250918",    // Strongest reasoning
    // model: "claude-sonnet-4-20250514", // Default, balanced
    // model: "claude-haiku-4-5-20251001", // Fastest, for simple tasks
  },
});