Claude Agent SDK 完全指南：从零构建生产级 AI 智能体

Agent 开发2天前更新 vicvinc
15 0

Claude Agent SDK 完全指南：从零构建生产级 AI 智能体

如果你使用过 Claude Code，你就见识过 AI 智能体的真正能力：读取文件、运行命令、编辑代码、规划任务步骤。它不只是帮你写代码，而是像一个深思熟虑的工程师一样拥有问题并逐步解决。

Claude Agent SDK 就是这背后的引擎，现在你可以用它来解决任何问题。这是 Claude Code 的基础设施，以库的形式暴露出来。你得到了智能体循环、内置工具、上下文管理——所有你原本需要自己构建的东西。

本指南将从零开始构建一个代码审查智能体。完成后，你将拥有一个能够分析代码库、发现 Bug 和安全问题、返回结构化反馈的智能体。

更重要的是，你将理解 SDK 的工作原理，这样你就可以构建任何你需要的东西。

为什么选择 Claude Agent SDK？

传统 API 开发的痛点

使用原始 API 构建智能体时，你需要手动管理以下循环：

// 没有 SDK：你需要管理循环
let response = await client.messages.create({...});
while (response.stop_reason === "tool_use") {
  const result = yourToolExecutor(response.tool_use);
  response = await client.messages.create({ tool_result: result, ... });
}

这种方式在构建任何非平凡应用时会变得非常繁琐。

SDK 的优势

使用 SDK 后，Claude 会为你管理这个循环：

// 使用 SDK：Claude 管理循环
for await (const message of query({ prompt: "修复 auth.py 中的 bug" })) {
  console.log(message); // Claude 读取文件、发现 bug、编辑代码
}

开箱即用的工具集

SDK 提供了完整的内置工具，你无需自己实现：

工具 功能
Read 读取工作目录中的任何文件
Write 创建新文件
Edit 对现有文件进行精确编辑
Bash 运行终端命令
Glob 按模式查找文件
Grep 使用正则表达式搜索文件内容
WebSearch 搜索网络
WebFetch 获取并解析网页

快速开始

环境准备

前置条件：

  1. Node.js 18+ 已安装
  2. Anthropic API 密钥（在此获取）

步骤 1：安装 Claude Code CLI

Agent SDK 使用 Claude Code 作为运行时：

npm install -g @anthropic-ai/claude-code

安装后，在终端运行 claude 并按照提示进行身份验证。

步骤 2：创建项目

mkdir code-review-agent && cd code-review-agent
npm init -y
npm install @anthropic-ai/claude-agent-sdk
npm install -D typescript @types/node tsx

步骤 3：设置 API 密钥

export ANTHROPIC_API_KEY=your-api-key

步骤 4：第一个智能体

创建 agent.ts：

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

async function main() {
  for await (const message of query({
    prompt: "这个目录里有什么文件？",
    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);
        }
      }
    }

    if (message.type === "result") {
      console.log("
完成:", message.subtype);
    }
  }
}

main();

运行它：

npx tsx agent.ts

Claude 会使用 Glob 工具列出文件并告诉你发现了什么。

理解 query() 函数

query() 函数返回一个异步生成器，在 Claude 工作时流式传输消息。以下是关键消息类型：

for await (const message of query({ prompt: "..." })) {
  switch (message.type) {
    case "system":
      // 会话初始化信息
      if (message.subtype === "init") {
        console.log("会话 ID:", message.session_id);
        console.log("可用工具:", message.tools);
      }
      break;

    case "assistant":
      // Claude 的响应和工具调用
      for (const block of message.message.content) {
        if ("text" in block) {
          console.log("Claude:", block.text);
        } else if ("name" in block) {
          console.log("工具调用:", block.name);
        }
      }
      break;

    case "result":
      // 最终结果
      console.log("状态:", message.subtype); // "success" 或错误类型
      console.log("成本:", message.total_cost_usd);
      break;
  }
}

构建代码审查智能体

现在让我们构建一些有用的东西。创建 review-agent.ts：

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

async function reviewCode(directory: string) {
  console.log(`
🔍 开始代码审查: ${directory}
`);

  for await (const message of query({
    prompt: `审查 ${directory} 中的代码：
1. Bug 和潜在崩溃
2. 安全漏洞
3. 性能问题
4. 代码质量改进

请具体说明文件名和行号。`,
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep"],
      permissionMode: "bypassPermissions", // 自动批准读取操作
      maxTurns: 250
    }
  })) {
    // 显示 Claude 的分析过程
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("text" in block) {
          console.log(block.text);
        } else if ("name" in block) {
          console.log(`
📁 使用 ${block.name}...`);
        }
      }
    }

    // 显示完成状态
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(`
✅ 审查完成！成本: $${message.total_cost_usd.toFixed(4)}`);
      } else {
        console.log(`
❌ 审查失败: ${message.subtype}`);
      }
    }
  }
}

// 审查当前目录
reviewCode(".");

测试智能体

创建一个包含故意错误的文件 example.ts：

function processUsers(users: any) {
  for (let i = 0; i <= users.length; i++) { // 差一错误
    console.log(users[i].name.toUpperCase()); // 没有 null 检查
  }
}

function connectToDb(password: string) {
  const connectionString = `postgres://admin:${password}@localhost/db`;
  console.log("连接使用:", connectionString); // 记录敏感数据
}

async function fetchData(url) { // 缺少类型注解
  const response = await fetch(url);
  return response.json(); // 没有错误处理
}

运行审查：

npx tsx review-agent.ts

Claude 会识别出 Bug、安全问题并建议修复方案。

结构化输出

对于程序化使用，你需要结构化数据。SDK 支持 JSON Schema 输出：

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

const reviewSchema = {
  type: "object",
  properties: {
    issues: {
      type: "array",
      items: {
        type: "object",
        properties: {
          severity: {
            type: "string",
            enum: ["low", "medium", "high", "critical"]
          },
          category: {
            type: "string",
            enum: ["bug", "security", "performance", "style"]
          },
          file: { type: "string" },
          line: { type: "number" },
          description: { type: "string" },
          suggestion: { type: "string" }
        },
        required: ["severity", "category", "file", "description"]
      }
    },
    summary: { type: "string" },
    overallScore: { type: "number" }
  },
  required: ["issues", "summary", "overallScore"]
};

async function reviewCodeStructured(directory: string) {
  for await (const message of query({
    prompt: `审查 ${directory} 中的代码。识别所有问题。`,
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep"],
      permissionMode: "bypassPermissions",
      maxTurns: 250,
      outputFormat: {
        type: "json_schema",
        schema: reviewSchema
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      const review = message.structured_output as {
        issues: Array<{
          severity: string;
          category: string;
          file: string;
          line?: number;
          description: string;
          suggestion?: string;
        }>;
        summary: string;
        overallScore: number;
      };

      console.log(`
📊 代码审查结果
`);
      console.log(`评分: ${review.overallScore}/100`);
      console.log(`摘要: ${review.summary}
`);

      for (const issue of review.issues) {
        const icon = issue.severity === "critical" ? "🔴" :
                     issue.severity === "high" ? "🟠" :
                     issue.severity === "medium" ? "🟡" : "🟢";
        console.log(`${icon} [${issue.category.toUpperCase()}] ${issue.file}${issue.line ? `:${issue.line}` : ""}`);
        console.log(`   ${issue.description}`);
        if (issue.suggestion) {
          console.log(`   💡 ${issue.suggestion}`);
        }
        console.log();
      }
    }
  }
}

reviewCodeStructured(".");

权限管理

默认情况下，SDK 在执行工具前会请求批准。你可以自定义这个行为：

权限模式

options: {
  // 标准模式 - 提示批准
  permissionMode: "default",

  // 自动批准文件编辑
  permissionMode: "acceptEdits",

  // 无提示（谨慎使用）
  permissionMode: "bypassPermissions"
}

自定义权限处理器

对于细粒度控制，使用 canUseTool：

options: {
  canUseTool: async (toolName, input) => {
    // 允许所有读取操作
    if (["Read", "Glob", "Grep"].includes(toolName)) {
      return { behavior: "allow", updatedInput: input };
    }

    // 阻止对某些文件的写入
    if (toolName === "Write" && input.file_path?.includes(".env")) {
      return {
        behavior: "deny",
        message: "不能修改 .env 文件"
      };
    }

    // 允许其他所有操作
    return { behavior: "allow", updatedInput: input };
  }
}

子智能体

对于复杂任务，你可以创建专门的子智能体：

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

async function comprehensiveReview(directory: string) {
  for await (const message of query({
    prompt: `对 ${directory} 进行全面的代码审查。
使用 security-reviewer 检查安全问题，使用 test-analyzer 分析测试覆盖率。`,
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep", "Task"], // Task 启用子智能体
      permissionMode: "bypassPermissions",
      maxTurns: 250,
      agents: {
        "security-reviewer": {
          description: "安全专家，用于漏洞检测",
          prompt: `你是一位安全专家。专注于：
- SQL 注入、XSS、CSRF 漏洞
- 暴露的凭证和密钥
- 不安全的数据处理
- 认证/授权问题`,
          tools: ["Read", "Grep", "Glob"],
          model: "sonnet"
        } as AgentDefinition,

        "test-analyzer": {
          description: "测试覆盖率和质量分析器",
          prompt: `你是一位测试专家。分析：
- 测试覆盖率缺口
- 缺失的边界情况
- 测试质量和可靠性
- 额外测试的建议`,
          tools: ["Read", "Grep", "Glob"],
          model: "haiku" // 使用更快的模型进行简单分析
        } as AgentDefinition
      }
    }
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("text" in block) {
          console.log(block.text);
        } else if ("name" in block && block.name === "Task") {
          console.log(`
🤖 委托给: ${(block.input as any).subagent_type}`);
        }
      }
    }
  }
}

comprehensiveReview(".");

会话管理

对于多轮对话，捕获并恢复会话：

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

async function interactiveReview() {
  let sessionId: string | undefined;

  // 初始审查
  for await (const message of query({
    prompt: "审查这个代码库并识别前 3 个问题",
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep"],
      permissionMode: "bypassPermissions",
      maxTurns: 250
    }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }
    // ... 处理消息
  }

  // 使用同一会话进行后续问题
  if (sessionId) {
    for await (const message of query({
      prompt: "现在展示如何修复最关键的问题",
      options: {
        resume: sessionId, // 继续对话
        allowedTools: ["Read", "Glob", "Grep"],
        maxTurns: 250
      }
    })) {
      // Claude 记得之前的上下文
    }
  }
}

Hooks（钩子）

Hooks 让你拦截和自定义智能体行为：

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

const auditLogger: HookCallback = async (input, toolUseId, { signal }) => {
  if (input.hook_event_name === "PreToolUse") {
    const preInput = input as PreToolUseHookInput;
    console.log(`[审计] ${new Date().toISOString()} - ${preInput.tool_name}`);
  }
  return {}; // 允许操作
};

const blockDangerousCommands: HookCallback = async (input, toolUseId, { signal }) => {
  if (input.hook_event_name === "PreToolUse") {
    const preInput = input as PreToolUseHookInput;
    if (preInput.tool_name === "Bash") {
      const command = (preInput.tool_input as any).command || "";
      if (command.includes("rm -rf") || command.includes("sudo")) {
        return {
          hookSpecificOutput: {
            hookEventName: "PreToolUse",
            permissionDecision: "deny",
            permissionDecisionReason: "危险命令被阻止"
          }
        };
      }
    }
  }
  return {};
};

for await (const message of query({
  prompt: "清理临时文件",
  options: {
    model: "opus",
    allowedTools: ["Bash", "Glob"],
    maxTurns: 250,
    hooks: {
      PreToolUse: [
        { hooks: [auditLogger] },
        { matcher: "Bash", hooks: [blockDangerousCommands] }
      ]
    }
  }
})) {
  // ...
}

成本追踪

追踪 API 成本以便计费：

for await (const message of query({ prompt: "..." })) {
  if (message.type === "result" && message.subtype === "success") {
    console.log("总成本:", message.total_cost_usd);
    console.log("令牌使用:", message.usage);

    // 按模型分解（对子智能体有用）
    for (const [model, usage] of Object.entries(message.modelUsage)) {
      console.log(`${model}: $${usage.costUSD.toFixed(4)}`);
    }
  }
}

生产级代码审查智能体

这里有一个将所有内容整合在一起的生产就绪智能体：

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

interface ReviewResult {
  issues: Array<{
    severity: "low" | "medium" | "high" | "critical";
    category: "bug" | "security" | "performance" | "style";
    file: string;
    line?: number;
    description: string;
    suggestion?: string;
  }>;
  summary: string;
  overallScore: number;
}

const reviewSchema = {
  type: "object",
  properties: {
    issues: {
      type: "array",
      items: {
        type: "object",
        properties: {
          severity: {
            type: "string",
            enum: ["low", "medium", "high", "critical"]
          },
          category: {
            type: "string",
            enum: ["bug", "security", "performance", "style"]
          },
          file: { type: "string" },
          line: { type: "number" },
          description: { type: "string" },
          suggestion: { type: "string" }
        },
        required: ["severity", "category", "file", "description"]
      }
    },
    summary: { type: "string" },
    overallScore: { type: "number" }
  },
  required: ["issues", "summary", "overallScore"]
};

async function runCodeReview(directory: string): Promise<ReviewResult | null> {
  console.log(`
${"=".repeat(50)}`);
  console.log(`🔍 代码审查智能体`);
  console.log(`📁 目录: ${directory}`);
  console.log(`${"=".repeat(50)}
`);

  let result: ReviewResult | null = null;

  for await (const message of query({
    prompt: `对 ${directory} 进行彻底的代码审查。

分析所有源文件中的：
1. Bug 和潜在运行时错误
2. 安全漏洞
3. 性能问题
4. 代码质量和可维护性

尽可能提供具体的文件路径和行号。`,
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep", "Task"],
      permissionMode: "bypassPermissions",
      maxTurns: 250,
      outputFormat: {
        type: "json_schema",
        schema: reviewSchema
      },
      agents: {
        "security-scanner": {
          description: "深度安全分析以检测漏洞",
          prompt: `你是一位安全专家。扫描：
- 注入漏洞（SQL、XSS、命令注入）
- 认证和授权缺陷
- 敏感数据暴露
- 不安全的依赖项`,
          tools: ["Read", "Grep", "Glob"],
          model: "sonnet"
        } as AgentDefinition
      }
    }
  })) {
    // 进度更新
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("name" in block) {
          if (block.name === "Task") {
            console.log(`🤖 委托给: ${(block.input as any).subagent_type}`);
          } else {
            console.log(`📂 ${block.name}: ${getToolSummary(block)}`);
          }
        }
      }
    }

    // 最终结果
    if (message.type === "result") {
      if (message.subtype === "success" && message.structured_output) {
        result = message.structured_output as ReviewResult;
        console.log(`
✅ 审查完成！成本: $${message.total_cost_usd.toFixed(4)}`);
      } else {
        console.log(`
❌ 审查失败: ${message.subtype}`);
      }
    }
  }

  return result;
}

function getToolSummary(block: any): string {
  const input = block.input || {};
  switch (block.name) {
    case "Read": return input.file_path || "文件";
    case "Glob": return input.pattern || "模式";
    case "Grep": return `"${input.pattern}" 在 ${input.path || "."}`;
    default: return "";
  }
}

function printResults(result: ReviewResult) {
  console.log(`
${"=".repeat(50)}`);
  console.log(`📊 审查结果`);
  console.log(`${"=".repeat(50)}
`);

  console.log(`评分: ${result.overallScore}/100`);
  console.log(`发现问题: ${result.issues.length}
`);
  console.log(`摘要: ${result.summary}
`);

  const byCategory = {
    critical: result.issues.filter(i => i.severity === "critical"),
    high: result.issues.filter(i => i.severity === "high"),
    medium: result.issues.filter(i => i.severity === "medium"),
    low: result.issues.filter(i => i.severity === "low")
  };

  for (const [severity, issues] of Object.entries(byCategory)) {
    if (issues.length === 0) continue;

    const icon = severity === "critical" ? "🔴" :
                 severity === "high" ? "🟠" :
                 severity === "medium" ? "🟡" : "🟢";

    console.log(`
${icon} ${severity.toUpperCase()} (${issues.length})`);
    console.log("-".repeat(30));

    for (const issue of issues) {
      const location = issue.line ? `${issue.file}:${issue.line}` : issue.file;
      console.log(`
[${issue.category}] ${location}`);
      console.log(`  ${issue.description}`);
      if (issue.suggestion) {
        console.log(`  💡 ${issue.suggestion}`);
      }
    }
  }
}

// 运行审查
async function main() {
  const directory = process.argv[2] || ".";
  const result = await runCodeReview(directory);

  if (result) {
    printResults(result);
  }
}

main().catch(console.error);

运行它：

npx tsx review-agent.ts ./src

最佳实践与进阶技巧

1. 选择合适的模型

  • Opus 4.5：最复杂的任务，需要深度推理
  • Sonnet：平衡性能和成本，适合大多数场景
  • Haiku：简单任务，需要快速响应

2. 优化工具使用

只授予必要的工具权限，遵循最小权限原则：

allowedTools: ["Read", "Grep"] // 只授予读取权限

3. 使用结构化输出

对于程序化处理，始终使用 JSON Schema 输出：

outputFormat: {
  type: "json_schema",
  schema: yourSchema
}

4. 监控成本

在开发阶段使用 maxTurns 限制迭代次数：

maxTurns: 50 // 开发阶段
maxTurns: 250 // 生产环境

5. 错误处理

始终检查 message.subtype 以处理错误情况：

if (message.type === "result") {
  if (message.subtype === "success") {
    // 处理成功
  } else {
    // 处理错误
    console.error("错误:", message.subtype);
  }
}

最新动态（2026）

Claude Code 2.1.0 版本带来了重大更新：

  1. 技能热重载：修改技能后无需重启会话即可生效
  2. 上下文分叉：支持在子智能体上下文中运行技能
  3. Hooks 生命周期：支持在 frontmatter 中定义钩子
  4. 权限通配符：工具权限设置支持通配符（如 Bash(-h)）
  5. 远程协作：新增 /teleport 命令，可将会话传送至网页端

这些更新进一步提升了 Claude Agent SDK 的开发体验和生产能力。

总结

Claude Agent SDK 为构建生产级 AI 智能体提供了强大而灵活的框架。通过本指南，你应该已经掌握了：

  • ✅ query() 方法：核心智能体循环管理
  • ✅ 内置工具：Read、Write、Edit、Bash 等
  • ✅ 结构化输出：JSON Schema 格式化结果
  • ✅ 子智能体：专门化任务处理
  • ✅ 会话管理：多轮对话和上下文保持
  • ✅ Hooks：自定义和拦截行为
  • ✅ 权限管理：细粒度访问控制

现在你可以构建自己的智能体来解决实际问题。无论是代码审查、文档生成、数据分析还是工作流自动化，Claude Agent SDK 都为你提供了坚实的基础设施。

下一步：

参考资源：

© 版权声明
文章版权归作者所有，未经允许请勿转载。
下一篇

没有更多了...

相关文章

暂无评论

none
暂无评论...

热门标签

日榜周榜月榜
PagePlug – 开源低代码平台 | 可视化开发 企业级应用

PagePlug – 开源低代码平台 | 可视化开发 企业级应用

PagePlug是行云创新基于Appsmith开源项目打造的中国化低代码开发平台,支持企业级Web应用和小程序开发
支付宝小程序 — 蚂蚁集团生态商业开放平台

支付宝小程序 — 蚂蚁集团生态商业开放平台

支付宝小程序是蚂蚁集团旗下核心商业开放平台，依托支付宝10亿+用户和强大的商业能力，为开发者和企业提供公域推广、私域运营、插件体系、多端投放等完整的小程序开发与服务生态。平台支持AI智能体接入、金融科技能力开放，是服务业数字化转型的重要基础设施。
N8N – 开源工作流自动化与 AI Agent 编排平台 | AI 应用创新工坊

N8N – 开源工作流自动化与 AI Agent 编排平台 | AI 应用创新工坊

N8N 是领先的开源工作流自动化平台，支持 AI Agent 编排、跨平台数据同步、自动化报表生成。自托管免费，1600+ 集成，企业级自动化解决方案。
Coze 扣子 – 字节跳动零代码 AI 智能体开发平台

Coze 扣子 – 字节跳动零代码 AI 智能体开发平台

Coze是字节跳动推出的零代码AI智能体开发平台,提供可视化工作流编排、插件生态、知识库RAG、多平台一键部署
Wot Design Uni — 多端统一UI组件库 | Vue3+TS架构与70+高质量组件

Wot Design Uni — 多端统一UI组件库 | Vue3+TS架构与70+高质量组件

Wot Design Uni是基于Vue3+TypeScript开发的uni-app跨平台UI组件库,提供70+高质量组件
IconPark – 字节跳动矢量图标库 | 2600+开源图标与多风格支持

IconPark – 字节跳动矢量图标库 | 2600+开源图标与多风格支持

IconPark是字节跳动开源的矢量图标库,提供2600+高质量SVG图标,支持线性、填充、双色、多色4种主题。可在线自定义粗细、颜色、大小,提供Vue/React组件,完全免费开源,MIT协议,适合Web、移动端和PPT设计。
查看完整榜单