claude-agent-sdk

name	claude-agent-sdk
description	Reference for Claude Agent SDK (@anthropic-ai/claude-agent-sdk). MUST use when working with Claude Agent SDK, claude-agent-sdk package, or code that imports from @anthropic-ai/claude-agent-sdk. Covers the SDK's query API, tool configuration, hooks, subagents, MCP integration, and structured output. Do NOT use for generic agent development or other agent frameworks.

Claude Agent SDK

Build autonomous AI agents that read files, run commands, edit code, search the web, and more. The SDK provides the same tools, agent loop, and context management that power Claude Code.

Core Concept

The key design principle: give Claude a computer. By providing tools to run bash commands, edit files, create files, and search files, Claude can work like humans do on any digital task.

Agent Loop Pattern

Effective agents follow this feedback loop: gather context → take action → verify work → repeat

┌─────────────────────────────────────────────────────┐
│                    AGENT LOOP                       │
├─────────────────────────────────────────────────────┤
│  1. GATHER CONTEXT                                  │
│     - Read files, search codebase                   │
│     - Use subagents for parallel information        │
│     - Query external APIs via MCP                   │
│                                                     │
│  2. TAKE ACTION                                     │
│     - Execute tools (Read, Write, Edit, Bash)       │
│     - Generate and run code                         │
│     - Call external services                        │
│                                                     │
│  3. VERIFY WORK                                     │
│     - Run linters, tests, type checkers             │
│     - Visual feedback (screenshots)                 │
│     - LLM-as-judge for fuzzy validation             │
│     - Apply deterministic rules                     │
└─────────────────────────────────────────────────────┘

Quick Start

Installation

npm install -g @anthropic-ai/claude-code
npm install @anthropic-ai/claude-agent-sdk
export ANTHROPIC_API_KEY=your-api-key

Minimal Agent (TypeScript)

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

async function main() {
  for await (const message of query({
    prompt: "What files are in this directory?",
    options: {
      model: "opus",
      allowedTools: ["Glob", "Read"],
      maxTurns: 250
    }
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("text" in block) console.log(block.text);
      }
    }
  }
}
main();

Minimal Agent (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"])
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Reference Documentation

For detailed implementation patterns, see:

• api_reference.md: Complete API, options, hooks, subagents, V2 API
• PATTERNS.md: Code review, research, automation, chat patterns
• TOOLS.md: Built-in tools and MCP integration
• PRODUCTION.md: Deployment, sandboxing, security, monitoring

Scripts

• create_agent.ts: Generate new agent projects from templates

Built-in Tools

Tool	Purpose
Read	Read any file in working directory
Write	Create new files
Edit	Make precise edits to existing files
Bash	Run terminal commands
Glob	Find files by pattern
Grep	Search file contents with regex
WebSearch	Search the web
WebFetch	Fetch and parse web pages
Task	Spawn subagents for parallel work

Agent Types by Use Case

Code Review Agent: allowedTools: ["Read", "Glob", "Grep"] File Automation Agent: allowedTools: ["Read", "Write", "Edit", "Bash", "Glob"] Research Agent: allowedTools: ["WebSearch", "WebFetch", "Read", "Write"] Multi-Agent Orchestrator: allowedTools: ["Read", "Glob", "Grep", "Task"]

Key Options

options: {
  model: "opus" | "sonnet" | "haiku",  // Model selection
  maxTurns: 250,                        // Max agent iterations
  allowedTools: [...],                  // Tools available to agent
  permissionMode: "default" | "acceptEdits" | "bypassPermissions",
  systemPrompt: "...",                  // Custom system instructions
  settingSources: ["project"],          // Load skills from .claude/skills/
  outputFormat: { type: "json_schema", schema: {...} }  // Structured output
}

Message Stream Types

for await (const message of query({...})) {
  switch (message.type) {
    case "system":    // Session init, available tools
    case "assistant": // Claude's responses and tool calls
    case "result":    // Final result with cost info
  }
}

When to Use Each Pattern

Simple task, single file: Direct query with basic tools Complex analysis: Add structured output schema Large codebase: Use subagents for parallel search External integrations: Add MCP servers for custom tools Production deployment: Add hooks for auditing and guardrails

Verification Strategies

1. Linting/Type checking: Run after code generation
2. Visual feedback: Screenshot renders for UI work
3. Deterministic rules: Hooks that check specific conditions
4. LLM-as-judge: Subagent evaluates output quality

Context Engineering

The file system represents information that could be pulled into context:

• Use CLAUDE.md for project-level instructions
• Organize data folders for agentic search
• Let Claude use grep/tail on large files
• Use subagents to isolate context and return summaries