Claude Code Agent SDK 完全指南：用 Claude 的引擎构建你自己的 AI Agent

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: "解释一下什么是 Agent Loop",
  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="解释一下什么是 Agent Loop",
    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,           // 用户输入
  options: {
    model?: string,         // 模型选择，默认 claude-sonnet-4-20250514
    systemPrompt?: string,  // 完全替换默认系统提示
    appendSystemPrompt?: string, // 追加到默认系统提示末尾
    allowedTools?: string[], // 工具白名单
    disallowedTools?: string[], // 工具黑名单
    permissionMode?: string, // 权限模式
    cwd?: string,           // 工作目录
    mcpServers?: Record<string, McpServerConfig>, // MCP 服务器
    maxTurns?: number,      // 最大轮次
  },
})

// 只允许读文件和搜索，禁止任何写操作
options: {
  allowedTools: ["Read", "Glob", "Grep"],
}

type Message =
  | { type: "assistant"; message: AssistantMessage }  // Claude 的回复
  | { type: "user"; message: UserMessage }            // 工具结果（自动生成）
  | { type: "result"; result: ResultMessage }          // 最终结果

import { query, type Message } from "@anthropic-ai/claude-code";
 
// 第一轮
const history: Message[] = [];
for await (const msg of query({ prompt: "读一下 package.json" })) {
  history.push(msg);
}
 
// 第二轮，带上历史
for await (const msg of query({
  prompt: "把 name 字段改成 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: "你是一个代码审查助手",
});
 
// 多轮对话，session 自动管理上下文
const response1 = await session.send("分析 src/auth.ts 的安全性");
const response2 = await session.send("刚才发现的问题，给出修复方案");
 
// 流式输出
for await (const chunk of session.stream("总结所有发现")) {
  process.stdout.write(chunk);
}

// 代码审查 Agent：只读，不能修改任何东西
const reviewAgent = query({
  prompt: "审查这个 PR 的代码质量",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Bash(git diff)"],
    permissionMode: "plan",
  },
});
 
// 文档生成 Agent：可以读代码、写 Markdown
const docAgent = query({
  prompt: "为 src/api/ 目录生成 API 文档",
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Write", "Edit"],
    permissionMode: "autoEdit",
  },
});

allowedTools: [
  "Bash(npm test)",      // 只允许运行测试
  "Bash(git diff)",      // 只允许查看 diff
  "Bash(git log)",       // 只允许查看日志
]

// 生产环境推荐配置
query({
  prompt: userInput,
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    permissionMode: "plan",
    maxTurns: 10,
    cwd: "/app/workspace",
  },
});

query({
  prompt: "查看最近的 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:
        "你是一个数据库分析助手。用户会问关于数据的问题，" +
        "你可以通过 MCP 工具查询 PostgreSQL 数据库来回答。" +
        "查询前先了解表结构，避免全表扫描。",
      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;
}
 
// 使用
const answer = await dbQueryAgent("上个月新增了多少用户？按周统计");

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: `请审查当前分支相对于 ${baseBranch} 的所有代码变更。
 
要求：
1. 先运行 git diff ${baseBranch}...HEAD 查看变更
2. 逐文件分析，关注：安全漏洞、性能问题、逻辑错误、代码风格
3. 最后以 JSON 格式输出审查结果，格式如下：
{
  "summary": "总体评价",
  "issues": [
    { "severity": "error|warning|info", "file": "文件路径", "line": 行号, "message": "问题描述" }
  ]
}
只输出 JSON，不要其他内容。`,
    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: `请为 ${sourceDir} 目录下的所有 TypeScript 文件生成 API 文档。
 
步骤：
1. 用 Glob 找到所有 .ts 文件
2. 逐个读取，提取导出的函数、类、接口
3. 为每个导出项生成文档，包含：描述、参数、返回值、使用示例
4. 将完整文档写入 ${outputFile}，使用 Markdown 格式`,
    options: {
      allowedTools: ["Read", "Glob", "Grep", "Write"],
      permissionMode: "autoEdit",
      maxTurns: 30,
    },
  })) {
    messages.push(message);
  }
 
  console.log(`文档已生成: ${outputFile}`);
}
 
// 使用
await generateApiDocs("src/api", "docs/API.md");

query({
  prompt: "重构 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: `你需要完成以下任务：
1. 审查 src/auth/ 目录的安全性
2. 审查 src/api/ 目录的 API 设计
3. 汇总两个审查结果
 
请使用子 Agent 并行处理前两个任务，然后汇总。`,
  options: {
    allowedTools: ["Read", "Glob", "Grep", "Agent"],
    maxTurns: 20,
  },
});

const controller = new AbortController();
 
// 5 秒后中断
setTimeout(() => controller.abort(), 5000);
 
try {
  for await (const message of query({
    prompt: "分析整个代码库的架构",
    options: { signal: controller.signal },
  })) {
    // 处理消息...
  }
} catch (err) {
  if (err.name === "AbortError") {
    console.log("任务已中断");
  }
}

// ci-review.ts — 在 PR 上自动运行代码审查
import { query } from "@anthropic-ai/claude-code";
 
async function ciReview() {
  const messages = [];
 
  for await (const msg of query({
    prompt: "审查当前 PR ���代码变更，输出 Markdown 格式的审查报告",
    options: {
      allowedTools: [
        "Bash(git diff)",
        "Bash(git log)",
        "Read",
        "Glob",
        "Grep",
      ],
      permissionMode: "plan", // 只读，不修改任何文件
      maxTurns: 15,
    },
  })) {
    messages.push(msg);
  }
 
  const result = messages.find((m) => m.type === "result");
  return result?.result?.text ?? "审查完成，未发现问题。";
}

# .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 }}

# 先安装 CLI
npm install -g @anthropic-ai/claude-code
 
# 再安装 SDK
npm install @anthropic-ai/claude-code

query({
  prompt: "...",
  options: {
    model: "claude-opus-4-20250918",    // 最强推理
    // model: "claude-sonnet-4-20250514", // 默认，平衡性能和成本
    // model: "claude-haiku-4-5-20251001", // 最快，适合简单任务
  },
});