1. 简介：开启你的AI代理构建之旅

1.1 引言

欢迎来到AI代理构建的世界！如果你曾对能够自主分析代码、运行命令、甚至修复错误的AI感到好奇，那么本教程就是为你量身打造的。我们的目标清晰而具体：从零开始，一步步构建一个可以分析代码库、发现潜在问题并提供专业反馈的AI代码审查代理（Code Review Agent）。

本教程专为初学者设计，你不需要任何AI代理开发经验。只要跟着我们的步骤，你就能亲手创造出第一个属于自己的实用AI工具。

1.2 什么是 Claude Agent SDK？为什么它如此强大？

简单来说，Claude Agent SDK 是著名AI助手 Claude Code 背后的核心引擎。它是一个强大的工具库，让你能够轻松地构建、测试和部署自己的AI代理。

为了让你更直观地理解SDK的优势，让我们对比一下使用原生API和使用Agent SDK构建代理的区别：

特性 使用原生API 使用Agent SDK
循环管理 开发者需要手动编写循环逻辑，不断调用模型、检查工具使用、返回结果，过程繁琐。 SDK自动处理整个代理循环，你只需关注业务逻辑。
工具执行 需要自己实现所有工具（如文件读取、网络搜索）的调用和结果处理。 内置了一系列即开即用的强大工具（文件操作、Shell命令、网络搜索等）。
代码简洁性 代码冗长，需要管理大量的状态和API调用细节。 代码极其简洁，几行代码就能启动一个强大的代理会话。

下面的代码片段生动地展示了这种简洁性带来的巨大差异：

// 使用原生API：你需要手动管理整个循环
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, ... });
}

// 使用Agent SDK：Claude 会为你处理好一切
for await (const message of query({ prompt: "修复 auth.py 中的错误" })) {
  console.log(message); // Claude 会自动读取文件、发现错误并修改代码
}

它为何如此强大？内置的工具集是关键。 Agent SDK 的一个核心优势在于它为你处理了所有繁琐的底层逻辑，让你能够将精力完全集中在定义代理的目标和功能上。它自带一套强大的预置工具，极大地加快了开发速度，让你不必从零开始实现常见的文件和命令行操作。

  • • Read / Write / Edit: 强大的文件系统操作能力。

  • • Glob / Grep: 像专业的开发者一样查找文件和搜索代码内容。

  • • Bash: 赋予代理执行终端命令的能力。

  • • WebSearch / WebFetch: 让代理能够上网搜索信息和获取网页内容。

核心理念：消息流 (The Core Idea: The Message Stream)

在深入编写代码之前，理解SDK的核心工作方式至关重要：异步消息流。你可以把代理的整个工作过程想象成一个持续不断的事件流。从代理启动、思考、调用工具，到最终给出答案，每一步都会通过这个流发送一条消息。

我们之后会用 for await...of 循环来监听这个流。理解不同类型的消息是掌握SDK的关键：

  • • system: 这类消息通常在会话开始时出现，告诉你一些初始化信息，比如唯一的会话ID或可用的工具列表。

  • • assistant: 这是最重要的消息类型之一，它包含了Claude的“思考过程”——它的文本回复、它决定使用哪个工具的调用请求等。

  • • result: 当代理完成所有任务（或失败）时，会发送一条 result 消息。这条消息包含了最终的状态（如 success）、总成本，以及我们后面会用到的结构化输出。

提前理解这个概念，会让你在看到第一个代码示例时豁然开朗。

1.3 我们将要构建什么？

在本教程中，我们将构建一个代码审查代理，它具备以下三个核心功能：

  • • 分析代码：能够深入代码库，分析其中的错误、安全漏洞和性能问题。

  • • 自主操作：能够像人类工程师一样，自主地使用工具读取文件和搜索代码。

  • • 结构化反馈：能够提供格式清晰、可供程序直接使用的结构化审查报告。

1.4 技术栈

我们将使用以下现代且强大的技术栈来完成本次构建：

  • • 运行时 (Runtime): Claude Code CLI - 这是Agent SDK的官方运行环境。

  • • SDK: @anthropic-ai/claude-agent-sdk - 我们的核心工具库。

  • • 语言 (Language): TypeScript - 提供强大的类型安全，让代码更健壮。

  • • 模型 (Model): Claude Opus 4.5 - Anthropic最强大的模型之一，具备卓越的推理能力。

理论知识已经足够，现在让我们卷起袖子，开始搭建我们的开发环境吧！

2. 准备工作

2.1 必备前提

在开始之前，请确保你的电脑上已经准备好以下两样东西：

  1. 1. Node.js: 你需要 18+ 或更高的版本。

  2. 2. Anthropic API 密钥: 这是让你的代理能够调用Claude模型的“通行证”。你可以在 Anthropic 控制台 免费获取。

2.2 环境设置

我们将通过三个简单的步骤来完成所有设置。

  1. 1. 第一步：安装 Claude Code CLI

  2. 2. Claude Code CLI 是Agent SDK的运行环境。打开你的终端，输入以下命令进行全局安装：

  3. 3. 安装完成后，运行 claude 命令，并按照提示完成身份验证。

  4. 4. 第二步：创建项目并安装依赖

  5. 5. 接下来，让我们为代码审查代理创建一个专属的项目目录，并安装所有必需的依赖包。

  • • @anthropic-ai/claude-agent-sdk 是我们的主角——核心SDK。

  • • typescript, @types/node, tsx 是帮助我们编写和运行TypeScript代码的开发工具。

  1. 6. 第三步：设置你的 API 密钥

  2. 7. 这是至关重要的一步。执行以下命令，将你的Anthropic API密钥设置为环境变量。SDK会自动读取这个变量来进行API调用。

  3. 8. 注意： 请将 your-api-key 替换为你自己真实的API密钥。

太棒了！你的开发环境已经准备就绪。现在，让我们来编写并运行第一个简单的AI代理，感受一下SDK的魔力。

3. 第一个Agent程序

3.1 创建你的第一个代理文件

在你的项目目录 code-review-agent 中，创建一个名为 agent.ts 的新文件，并将以下代码粘贴进去：

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);
        }
      }
    }
    if (message.type === "result") {
      console.log("\nDone:", message.subtype);
    }
  }
}

main();

3.2 代码逐行解析

这段代码虽然简短，但包含了与代理交互的核心要素。让我们来逐一解析：

  • • import { query }: 这是我们从SDK中导入的核心函数，它是所有代理交互的入口点。

  • • query() 函数: 这个函数负责启动一个代理会话。我们向它传递初始指令和配置。

  • • prompt 参数: 这是我们给代理下达的初始指令。在这里，我们让它“找出当前目录下的所有文件”。

  • • options 对象: 这个对象用于配置代理的行为。

    • • model: 指定我们希望使用的Claude模型。"opus" 是 Anthropic 最强大模型家族的别名 (对于生产环境或需要可复现结果的场景，你可能会使用更具体的版本名称，如 claude-opus-4-5-20251101)。

    • • allowedTools: 一个数组，定义了允许代理使用的工具集。这里我们只允许它使用 Glob（按模式查找文件）和 Read（读取文件内容）。

    • • maxTurns: 代理在放弃任务前，可以与工具进行交互的最大回合数。

  • • for await...of 循环: 这是一个异步循环，它会持续从我们之前讨论过的“消息流”中接收消息。代理在工作过程中的每一步（思考、使用工具、回复）都会产生一条消息。

  • • if (message.type === "assistant"): 我们在这里从消息流中筛选出类型为 assistant 的消息，这些消息包含了Claude的文本回复。然后我们将其打印到控制台。

3.3 运行并观察结果

在你的终端中，运行以下命令：

npx tsx agent.ts

你会看到，Claude接收到指令后，会决定使用 Glob 工具来列出当前目录下的文件，最后以一段文本的形式告诉你它找到了哪些文件。

现在你已经成功运行了一个简单的代理，它能够使用工具并与你交流。接下来，让我们在这个基础上构建一个更强大、更具实际用途的代码审查代理。

4. 构建核心功能：一个真正的代码审查代理

4.1 创建代码审查代理文件

让我们创建一个新文件 review-agent.ts，并填入以下更专业的代码：

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

async function reviewCode(directory: string) {
  console.log(`\n🔍 Starting code review for: ${directory}\n`);

  for await (const message of query({
    prompt: `Review the code in ${directory} for:
1. Bugs and potential crashes
2. Security vulnerabilities
3. Performance issues
4. Code quality improvements
Be specific about file names and line numbers.`,
    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(`\n📁 Using ${block.name}...`);
        }
      }
    }

    // 显示任务完成状态
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(`\n✅ Review complete! Cost: $${message.total_cost_usd.toFixed(4)}`);
      } else {
        console.log(`\n❌ Review failed: ${message.subtype}`);
      }
    }
  }
}

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

4.2 代码升级解析

与上一个简单的代理相比，这段代码有了显著的升级：

  • • 更复杂的 prompt: 我们不再是简单地提问，而是通过一个有序列表，向代理下达了一个非常具体且复杂的审查任务，涵盖了错误、漏洞、性能和代码质量四个方面。

  • • 新的工具集 allowedTools: 我们为代理配备了审查代码所需的核心工具组合。这模拟了人类开发者的思考过程：首先，代理使用 Glob 来找到所有相关的源文件（就像查看文件树一样）。然后，它使用 Read 来打开并理解每个文件的内容。最后，如果需要查找特定模式（如一个被弃用的函数名），它会使用 Grep 来在整个代码库中进行搜索。

  • • 新的选项 permissionMode: 你可能会想：“在开发过程中，如果每次代理尝试读取文件都得手动批准，这会打断我的流程。” 为了解决这个问题，SDK提供了一个便捷的选项 permissionMode: "bypassPermissions"。它告诉SDK自动批准所有读取文件的操作，让流程更加顺畅。

  • • 更丰富的日志输出: 代码现在不仅打印Claude的文本回复，还会打印出它正在使用哪个工具 (Using Glob...)，这让代理的工作过程变得更加透明，便于我们观察和调试。

4.3 创建一个用于测试的“问题”文件

为了验证我们的代理是否有效，我们需要给它一些“有问题”的代码来审查。在项目根目录下创建一个名为 example.ts 的新文件，并粘贴以下代码：

function processUsers(users: any) {
  for (let i = 0; i <= users.length; i++) { // 越界错误
    console.log(users[i].name.toUpperCase()); // 未进行空值检查
  }
}

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

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

这段代码中故意留下了几个常见问题：

  • • 越界错误：for 循环的条件 i <= users.length 会导致访问一个不存在的数组元素。

  • • 空值引用：如果 users[i] 为 null 或 undefined，users[i].name 将导致程序崩溃。

  • • 敏感数据泄露：将包含密码的数据库连接字符串直接打印到日志中，这是一个严重的安全漏洞。

  • • 类型和错误处理缺失：函数参数没有类型注解，fetch 调用也没有任何错误处理逻辑。

4.4 运行你的代码审查员

一切准备就绪！现在，让我们启动代码审查代理：

npx tsx review-agent.ts

观察你的终端输出。你会看到Claude开始分析，并实时打印出它对 example.ts 文件中每一个问题的发现，包括具体的文件名、行号以及详细的修复建议。

做得好！你的代理现在已经可以像一个初级工程师一样找出代码中的问题了。但为了让审查结果更易于被其他程序使用，我们需要让它输出结构化的数据，比如JSON格式。

5. 升级代理：输出结构化数据

5.1 为什么需要结构化输出？

人类可以轻松理解自由格式的文本，但对于计算机程序来说，处理这些文本非常困难。如果审查结果是结构化的（如JSON格式），我们就可以轻松地将其集成到CI/CD流程、生成报告或在仪表盘上展示。

5.2 定义输出格式：JSON Schema

为了告诉Claude我们想要的输出格式，我们需要定义一个“模板”，这个模板就是 JSON Schema。它精确地描述了JSON对象应该包含哪些字段、每个字段的类型是什么，就像一份合同一样，确保代理返回的数据是我们期望的样子。

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

这个Schema告诉Claude，最终的输出必须是一个包含 issues 数组、summary 字符串和 overallScore 数字的对象。同时，它还详细定义了issues数组中每个问题对象的结构。

5.3 编写输出结构化数据的代理

现在，我们可以修改 review-agent.ts 文件（或创建一个新文件）来使用这个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: `Review the code in ${directory}. Identify all issues.`,
    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(`\n📊 Code Review Results`);
      console.log(`✅ Review complete! Cost: $${message.total_cost_usd.toFixed(4)}\n`);
      console.log(`Score: ${review.overallScore}/100`);
      console.log(`Summary: ${review.summary}\n`);

      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(".");

这里的关键改动有两处：

  1. 1. options 中的 outputFormat: 我们在 options 对象中新增了 outputFormat 字段，并将我们定义的 reviewSchema 传递给它。这明确地告诉代理，最终结果必须符合这个Schema。

  2. 2. 处理 result 消息: 这也揭示了 assistant 和 result 消息类型的核心区别：assistant 流展示的是代理的过程（它的思考和工具使用），而最终的、经过验证的、符合Schema的产品则只在任务结束时的 result 消息中交付一次。我们通过 message.structured_output 来访问这个JSON对象。

你现在得到的不仅仅是文本，而是一个可以被其他系统集成的、机器可读的专业审查报告。这就是将AI代理融入自动化工作流程的关键一步。

再次运行 npx tsx review-agent.ts，你将看到一个格式精美、结构清晰的专业代码审查报告！

恭喜你！你已经成功构建了一个功能强大且能输出专业审查报告的AI代码审查代理。你掌握了SDK的核心用法，是时候看看未来还有哪些更酷的功能等待你去探索了。

6. 总结与下一步

6.1 你已经掌握的核心技能

通过本教程，你已经从零开始，掌握了构建一个AI代理所需的核心技能：

  • • 环境设置: 如何安装CLI、创建项目和配置API密钥。

  • • 发起代理查询: 如何使用核心的 query() 函数启动代理并与之交互。

  • • 配置代理行为: 如何通过 options 对象来指定模型、授权工具和设置权限模式。

  • • 处理实时消息: 如何从异步消息流中获取代理的思考过程（assistant 消息）和最终结果（result 消息）。

  • • 实现结构化输出: 如何利用JSON Schema来获得格式统一、可供程序直接使用的数据。

6.2 深入探索：未来学习路径

你刚刚构建的代理仅仅是一个开始。Claude Agent SDK 提供了更多强大的功能，可以帮助你构建更复杂的应用。以下是一些值得你深入探索的方向：

  • • 子代理 (Subagents): 当任务变得异常复杂时怎么办？你可以将一个庞大的任务分解给多个专门的子代理来协同处理，就像一个团队一样。了解更多

  • • 自定义工具 (Custom Tools): 如果你想让代理与你自己的API或数据库交互呢？通过创建自定义工具，你可以赋予代理与任何系统对话的能力。了解更多

  • • 会话管理 (Session Management): 如果希望代理能记住你们上次的对话，并在下一次继续呢？会话管理是构建能维持上下文的多轮对话代理的关键。了解更多

  • • 钩子 (Hooks): 如何在代理执行的关键节点（如使用工具前）注入自定义逻辑？钩子机制让你能实现精细的日志记录、安全检查或行为修改。了解更多

  • • 成本追踪 (Cost Tracking): 如何精确地知道每次代理运行花费了多少钱？SDK内置的成本追踪功能可以清晰地告诉你每一次调用的Token用量和费用。了解更多

  • • 文件检查点 (File Checkpointing): 允许代理修改文件总让人有点担心。这个功能让代理的所有文件修改都可被追踪，甚至可以一键恢复到修改前的状态。了解更多

  • • 技能 (Skills): 如何将一套工具和指令打包成可复用的能力？技能让你能创建标准化的、可插拔的功能模块。了解更多

  • • 生产部署 (Production Deployment): 当你准备好将代理投入真实世界时，如何安全、可靠地部署它？这里有关于容器化、CI/CD和安全沙箱的最佳实践。了解更多

值得注意的是，本指南涵盖的是SDK的V1版本。V2版本目前正在积极开发中。请保持关注，因为工具链在不断进化。

你已经迈出了最重要的一步。现在，世界充满了等待被解决的问题，而你拥有了创造解决方案的强大工具。继续探索，不断创造，看看你能用AI代理构建出怎样令人惊叹的应用吧！ 

我们创建了一个高质量的技术交流群，与优秀的人在一起，自己也会优秀起来，赶紧 点击加群 ，享受一起成长的快乐。

推荐阅读

CLAUDE.md 全方位指南：构建高效 AI 开发上下文

Claude Code 最佳实践的 8 条黄金法则

彻底改变你与 AI 编码方式的五个新范式

Anthropic 如何评估 AI Agent

# 人工智能
Logo
乐奇 Rokid 开放社区

更多推荐

5分钟零门槛上手：UI-TARS桌面版视觉语言模型智能自动化完全指南

UI-TARS桌面版是一款革命性的开源多模态AI代理应用，它通过先进的视觉语言模型技术，让你能够使用自然语言指令直接控制计算机界面。想象一下，只需告诉AI"帮我整理桌面文件"或"打开VS Code并设置自动保存"，它就能像真人一样操作你的电脑！这就是UI-TARS带来的智能自动化体验。无论你是普通用户想要简化日常工作，还是开发者寻求自动化解决方案，这个工具都能为你带来前所未有的便利。## 🚀

avatar 乐奇 Rokid 开放社区

Notepad--跨平台文本编辑器：国产软件替代的技术架构与实践指南

Notepad--是一款面向Windows、Linux和macOS平台的轻量级文本编辑器，致力于为开发者提供高效、稳定的代码编辑解决方案。作为国产软件可替代方案的代表，该项目在信创UOS系统及各类Linux发行版上表现出色，通过Qt框架实现跨平台兼容性，为技术团队提供了自主可控的文本编辑工具。## 一、核心架构解析与多平台适配策略### 1.1 基于Qt框架的跨平台架构设计Notepad

avatar 乐奇 Rokid 开放社区

Palworld Host Save Fix：3步解决服务器迁移存档丢失问题

你是否在《幻兽帕鲁》服务器迁移时遇到了"强制创建新角色"的噩梦？投入上百小时培养的帕鲁、精心建造的基地、辛苦收集的资源，一夜之间化为乌有？Palworld Host Save Fix 正是为解决这一痛点而生的开源工具，它能让你在不同类型服务器间无缝迁移存档，完美保留所有角色数据和游戏进度。简单来说，这个工具就像是给你的游戏角色换一张新身份证，让新服务器能够正确识别并加载你原有的存档数据。##

avatar 乐奇 Rokid 开放社区