AI Agent 设计与实现

拆解 Claude.ai · Claude Code · Codex · Cursor 的 Agent 架构
2026-05-05 · 技术白皮书

一、工具调用的本质：模型能力 vs 系统工程

1.1 三层协作

工具调用是模型训练 + API 层转换 + 应用层执行三层协作的结果：

1.2 模型层：训练赋予的四个能力

1. 意图识别 — 判断"用户的请求是否需要外部信息或动作"
2. 工具选择 — 从可用工具列表中选最合适的（可以选多个）
3. 参数生成 — 根据工具 schema 生成正确的 JSON 参数
4. 结果整合 — 基于工具返回的结果，综合生成最终回答

这些能力是通过 Supervised Fine-Tuning (SFT) 和 RLHF 训练出来的。训练数据大致如下：

// 训练样本示例（简化）
System: You have tools: web_search(query), calculator(expr)
Human: 北京今天多少度？
Assistant: [tool_use: web_search("北京 今天 气温")]
Tool Result: 北京今日最高温 28°C，最低 18°C，晴
Assistant: 北京今天最高气温 28°C，最低 18°C，天气晴朗。

模型见过数百万条这样的样本后，学会了一个关键判断："我不知道答案 → 有可用工具 → 应该调用"。

1.3 API 层：看不见的翻译官

当你向 Anthropic API 发送带 tools 参数的请求时，API 层做了这些事：

API 层是双向翻译：

• 输入方向：把 tools JSON 转成模型理解的 prompt 文本
• 输出方向：检测模型输出中的工具调用格式，解析为结构化的 tool_use response

1.4 应用层：你写的循环

模型只负责"决定调用什么工具"。实际执行工具、管理上下文、控制循环全部是应用层的工作。这就是我们在 server.mjs 中写的 chat() 函数做的事。

二、Agent 核心架构：ReAct 与 Tool Use Loop

2.1 ReAct 范式

几乎所有现代 Agent 都遵循 ReAct（Reasoning + Acting）范式，由 Yao et al. (2022) 提出：

2.2 Tool Use Loop 的工程实现

ReAct 在工程上的实现就是一个 while 循环：

async function agentLoop(userMessage) {
  const messages = [systemPrompt, userMessage];

  for (let round = 0; round < MAX_ROUNDS; round++) {
    const response = await callLLM(messages, tools);

    if (response.stop_reason === "tool_use") {
      // 模型想用工具 → 执行 → 结果追加到 messages
      for (const toolCall of response.tool_uses) {
        const result = await executeTool(toolCall);
        messages.push(assistantMsg, toolResultMsg);
      }
      continue; // 下一轮 → 模型看到结果后继续推理
    }

    // 模型直接回答 → 结束循环
    return response.text;
  }
}

这段代码就是所有 Agent 的核心骨架。Claude.ai、Claude Code、Codex 本质上都是这个循环的不同实现。

2.3 关键设计决策

三、拆解 Claude.ai 的 Agent 设计

3.1 整体架构

3.2 工具清单与设计思路

Web Search

模型自主决定搜索词，可以多次搜索、逐步深入。这比传统的"用户勾选联网"体验更好，因为模型知道什么时候需要搜索、搜什么最有效。

Code Execution（Analysis Tool）

沙盒化的 JavaScript 运行环境。模型写代码 → 服务端在沙盒中执行 → 结果（文本/图表）返回给模型。典型用途：数据分析、数学计算、图表生成。

Artifacts

Claude.ai 最有辨识度的功能。本质是一个结构化输出工具：

• 模型调用 create_artifact，指定类型（React 组件/HTML/SVG/Markdown/Mermaid）
• 前端在右侧面板中渲染预览（iframe 沙盒）
• 支持版本迭代：用户说"改成蓝色"→ 模型生成 v2 → 可在版本间切换

Extended Thinking

不是传统意义的工具，而是模型的内部推理过程。通过 API 的 thinking 参数控制。模型在调用工具前先"思考"策略，用户可以看到思考过程。

3.3 System Prompt 设计

Claude.ai 的 system prompt 是整个 Agent 行为的蓝图。核心要素：

1. 身份定义 — "你是 Claude，由 Anthropic 开发"
2. 工具使用指导 — 什么时候用什么工具、不用工具的场景
3. Artifact 规范 — 什么内容该创建 Artifact、格式要求
4. 安全边界 — 拒绝什么请求、如何处理敏感内容
5. 输出风格 — 简洁、直接、不过度解释

四、拆解 Claude Code 的 Agent 设计

Claude Code 是一个比 claude.ai 复杂得多的 Agent 系统。它不是简单的聊天+工具，而是一个完整的软件工程 Agent。

4.1 架构总览

4.2 原生工具体系

Claude Code 提供了一套专为软件工程设计的工具：

4.3 权限系统：Human-in-the-Loop

Claude Code 的核心安全设计：每个工具调用都要用户批准（除非配置了自动批准）。

// 权限分级
读文件    → 通常自动批准（低风险）
写/编辑   → 需要用户确认（中风险，显示 diff）
Bash 命令 → 需要用户确认（高风险，显示命令）
git push  → 特别警告（不可逆操作）
rm -rf    → 强烈警告（破坏性操作）

这是 Agent 设计中的关键权衡：自主性 vs 安全性。完全自主的 Agent 效率高但风险大；完全需要批准的 Agent 安全但效率低。Claude Code 的方案是分级权限 + 可配置的自动批准。

4.4 上下文管理：解决 200K token 限制

长时间工作的 Agent 会累积大量上下文（代码内容、命令输出、工具结果）。Claude Code 的策略：

1. 自动压缩（auto-condense）— 当上下文接近限制时，用 AI 总结历史对话，保留关键信息
2. 标准截断— 保留首尾对话，丢弃中间部分（分 50% / 25% 两档）
3. 文件读取去重— 同一文件不重复读取
4. Prompt Caching— Anthropic 的 5 分钟缓存，避免重复发送 system prompt

4.5 子 Agent 系统

Claude Code 可以启动子 Agent 并行工作。每个子 Agent 有独立的上下文窗口和工具集。

// 主 Agent 启动两个子 Agent 并行
Agent({
  description: "研究 API 文档",
  prompt: "查找所有 REST endpoint..."
})
Agent({
  description: "运行测试套件",
  prompt: "执行 npm test 并分析失败..."
})

子 Agent 的设计要点：

• 主 Agent 发送自包含的 prompt（子 Agent 看不到主对话历史）
• 子 Agent 完成后返回摘要结果给主 Agent
• 可以在后台运行（run_in_background），主 Agent 继续其他工作
• 支持不同的 subagent_type（Explore、Plan 等，各有不同工具集）

4.6 Plan 模式

对于复杂任务，Claude Code 支持"先规划再执行"：

1. Plan 阶段：模型探索代码库、分析需求、提出实现方案（只用读取工具，不修改）
2. 用户审查：用户查看并批准/修改方案
3. Act 阶段：模型按照方案执行（读取+写入+命令）

Plan 和 Act 可以使用不同的模型（比如 Plan 用快速模型，Act 用强力模型）。

4.7 Hook 系统

Hook 是 Claude Code 的扩展点，允许用户在 Agent 生命周期的关键节点注入自定义行为：

五、横向对比：Claude Code vs Codex vs Cursor

5.1 定位差异

5.2 Agent 架构对比

Claude Code — 实时交互式 Agent

• 同步循环：用户发消息 → 模型回应 → 用户批准/修改 → 继续
• 人在回路：每一步都可审查和干预
• 透明度高：所有工具调用、文件修改对用户可见
• 上下文持久：一次对话可以持续数小时，自动压缩管理
• 适合场景：探索性开发、调试、复杂重构、需要判断的任务

Codex — 异步任务式 Agent

• 异步执行：用户提交任务 → Agent 在云端沙盒独立工作 → 完成后提交 PR
• 无人值守：不需要用户实时参与，完全自主
• 沙盒隔离：每个任务在独立容器中运行，有完整的 Linux 环境
• 结果交付：通过 Git PR 交付，用户事后审查
• 适合场景：明确的小任务（fix bug、加 feature）、批量处理、CI 集成

Cursor — IDE 集成式 Agent

• 三种模式：Tab 补全（快速、小模型）、Chat（问答）、Agent（全功能）
• 代码索引：建立整个代码库的语义索引，Agent 可以精确检索
• Apply 模型：专门训练的小模型用于高效应用代码修改（diff → 完整文件）
• IDE 深度集成：理解打开的文件、光标位置、LSP 诊断信息
• 适合场景：日常编码、快速迭代、IDE 工作流中的 AI 辅助

5.3 工具设计对比

5.4 核心设计哲学差异

Claude Code："我是你身边的结对编程伙伴。每一步我都征求你的意见，你随时可以纠正我。"
Codex："把任务交给我，去喝杯咖啡，回来看 PR 就行。"
Cursor："我住在你的 IDE 里，从自动补全到完整 Agent，无缝切换。"

5.5 安全模型对比

Codex 的沙盒模型最安全（Agent 在隔离容器中，无法影响生产环境），但也最受限（无法访问本地资源）。Claude Code 和 Cursor 在本地运行，能力最强但风险也最大，通过人工审批来控制风险。

六、设计你自己的 Agent 系统

基于以上分析，设计 Agent 时的关键检查清单：

6.1 核心循环

// 最小 Agent 骨架（你已经实现了这个！）
while (round < MAX_ROUNDS) {
  response = await llm.call(messages, tools);
  if (response.wants_tools) {
    results = await execute(response.tool_calls);
    messages.append(response, results);
  } else {
    return response.text;
  }
}

6.2 工具设计原则

1. 最小权限 — 每个工具只做一件事，避免万能工具
2. 清晰的 schema — description 和参数描述是模型决策的依据
3. 有限的输出 — 工具返回不要太长（会占用 context），做好截断
4. 优雅的错误 — 把错误信息返回给模型，让它自己决定下一步
5. 可观测性 — 每次工具调用都要让用户知道发生了什么

6.3 System Prompt 设计

1. 角色定义 — 你是谁、你的能力边界
2. 工具指导 — 什么时候用什么工具（正例和反例）
3. 输出规范 — 回复的格式、长度、语言
4. 安全约束 — 不能做什么

6.4 进阶能力路线图

你的 claude-lite 已经实现了第 1 级。后续可以按需添加：

结语

AI Agent 的核心并不神秘 — 它是一个 while 循环，里面是一个 LLM 调用和一组工具。真正的挑战在于工程细节：上下文管理、错误恢复、安全控制、用户体验。你的 claude-lite 已经走出了最关键的第一步：从"聊天机器人"变成了"Agent"。