前端

工具系统是 AI Agent 工程中最容易被低估的部分。很多人讨论 Agent 时，会把注意力放在模型能力、提示词技巧和工作流框架上，但真正让 Agent 能够完成任务的，是一组设计良好、边界清晰、可被安全调用的工具。

如果工具系统设计得不好，Agent 会出现很多问题：该查询的时候执行了写入，该传 ID 的地方传了标题，接口失败后不知道如何恢复，工具返回一大段日志导致模型无法判断结果。模型越强，这类问题越隐蔽，因为它可能用看似合理的语言掩盖底层执行错误。

## 工具系统的定位

工具系统是模型与外部世界之间的执行层。模型不应该直接访问数据库、文件系统或业务接口，而是通过工具间接访问。工具系统负责把外部能力包装成模型可理解、系统可控制的接口。

一个稳定的工具系统至少要回答几个问题：

- 这个工具能做什么？
- 什么时候应该使用？
- 需要哪些参数？
- 参数如何校验？
- 返回什么结构？
- 风险等级是什么？
- 是否需要用户确认？
- 失败时如何表达错误？

这些问题如果没有在工具层解决，就会被迫交给模型临场判断，而模型并不适合承担所有工程约束。

## 工具注册表

工具注册表是工具系统的入口。它记录所有可用工具，并为 Agent 提供当前场景下允许调用的工具集合。

一个工具注册项通常包含：

- name：工具名称；
- description：工具用途；
- parameters：参数 schema；
- execute：执行函数；
- riskLevel：风险等级；
- scopes：所需权限；
- outputSchema：返回结构；
- examples：调用示例。

有了注册表，系统可以按场景加载工具。例如内容管理 Agent 只加载 tag、article、tutorial、material 相关工具；代码 Agent 只加载文件、测试、构建相关工具。这样模型看到的工具更少，选择错误的概率也更低。

## 工具 schema 设计

工具 schema 不是简单的 TypeScript 类型，它是模型理解工具的说明书。schema 应该尽量具体，避免模糊表达。

例如创建文章工具不应该只写“创建文章”，而应该说明：title 是文章标题，short 是 URL 友好的唯一标识，content 是 Markdown 正文，tagIds 最多建议 3 个，draftId 必须存在或由 CLI 自动创建。

好的 schema 会让模型知道：什么是必填字段，什么字段可以省略，哪些参数有格式要求，哪些错误是常见错误。

## 参数校验

模型生成的参数必须校验。常见校验包括：

- ID 是否为数字；
- short 是否符合 URL 规则；
- URL 是否以 http 开头；
- 文件路径是否在允许目录内；
- tagIds 是否存在；
- 日期是否能解析；
- 数组长度是否超过限制。

校验失败时，工具应该返回结构化错误，而不是直接抛出一段堆栈。比如返回 errorType、field、message、suggestion。这样 Agent 才能根据错误修正参数或询问用户。

## 风险等级与确认

工具必须区分读操作和写操作。查询标签、读取文章、获取列表通常风险较低；创建文章、上传图片、修改配置是写操作；删除、发布、批量修改、发送消息属于高风险操作。

风险等级应该由系统强制执行，而不是只在提示词里提醒模型。比如 delete 工具必须要求确认，即使模型认为用户已经表达了意图，也要经过系统审批。

## 返回值结构

工具返回值应该为后续步骤服务。创建资源后，应该返回 id、short、url、status 等字段；查询列表应该返回 total 和 list；失败时应该返回明确错误类型。

如果工具只返回一句“创建成功”，Agent 后续就无法引用资源 ID。如果工具返回完整结构，Agent 可以继续绑定、验证或展示结果。

## 幂等性设计

Agent 经常需要重试，因此工具要考虑幂等性。创建标签前先查重，上传图片前判断是否已经是自有素材，创建文章前检查 short 是否存在。这样即使任务中断后重跑，也不会制造重复数据。

幂等性是长任务 Agent 的关键能力。没有幂等性，断点续跑和错误恢复都很难实现。

## 小结

稳定的工具系统不是把函数暴露给模型这么简单。它需要注册表、schema、参数校验、风险等级、结构化返回、幂等性和日志。工具层越清晰，Agent 的行为越可控，也越容易进入生产环境。

围绕工具注册、schema、参数校验、风险等级、错误格式和返回值设计，构建稳定可控的 Agent 工具系统。

AI Agent 实战教程 12：如何设计稳定的工具系统

很多 Agent Demo 都可以在一个文件里跑起来：定义一个模型、写几个工具函数、拼一段提示词，然后让模型决定下一步做什么。这个阶段很适合验证想法，但如果继续用这种结构承载真实业务，项目很快会失控。

AI Agent 项目天然比普通应用更容易变复杂。它既有模型调用，也有工具系统；既有提示词，也有状态机；既要处理业务数据，也要处理权限、日志、评测和错误恢复。因此，Agent 项目从一开始就应该有清晰的工程结构。

项目结构设计的目标不是追求目录数量，而是让每个模块职责清楚：谁负责理解任务，谁负责执行工具，谁负责保存状态，谁负责记录日志，谁负责评测质量。结构清晰后，团队协作、问题排查和后续扩展都会简单很多。

## 为什么 Agent 项目容易变乱

普通应用的核心逻辑通常比较明确。后端服务围绕 controller、service、model 组织；前端项目围绕页面、组件、状态和 API 组织。而 Agent 项目同时包含多个维度的逻辑：模型推理、工具调用、提示词、工作流、记忆、权限、审计、评测。

如果没有拆分，这些内容很容易混在一起。例如一个文件里既写系统提示词，又写工具函数，还写 API 请求，还保存任务状态。短期看开发很快，长期看每改一个工具都可能影响整个 Agent。

常见混乱表现包括：

- 所有工具都写在一个 tools 文件里；
- prompt 文本散落在代码中，无法版本化；
- 工具返回格式不统一；
- 状态只存在内存变量里，任务中断后无法恢复；
- 权限判断写在模型提示词里，而不是系统逻辑里；
- 没有统一日志，无法知道 Agent 为什么做出某个决策；
- 没有 evals，改一次 prompt 就可能破坏旧能力。

这些问题在演示时不明显，因为演示通常任务短、路径固定、数据少。但一旦进入真实系统，用户会提出模糊需求，接口会失败，权限会不足，任务会中断，工具会越来越多，单文件结构就很难维护。

## 推荐的目录分层

一个中等复杂度的 Agent 项目，可以从下面这些目录开始：

~~~text
agents/
tools/
workflows/
memory/
prompts/
evals/
logs/
config/
types/
~~~

这些目录不是固定标准，而是一种职责划分思路。项目小的时候可以合并，项目变大后可以继续细分。

### agents：定义 Agent 入口和角色

agents 目录用于定义不同 Agent 的角色和入口。例如：

- contentAgent：负责内容管理；
- codingAgent：负责代码修改；
- researchAgent：负责资料检索；
- taskAgent：负责待办和日程；
- reviewAgent：负责审查输出。

每个 Agent 不应该包含全部业务逻辑。它更像一个调度入口：接收用户目标，加载相关工具和 workflow，然后执行任务。

这样设计的好处是，新增一个 Agent 不会影响其他 Agent。比如你可以让 codingAgent 只加载文件和测试工具，而 contentAgent 只加载标签、文章和素材工具。

### tools：封装外部能力

tools 是 Agent 能力的边界。所有外部操作都应该通过工具封装，例如：

- 查询标签；
- 创建文章；
- 上传图片；
- 读取文件；
- 调用搜索 API；
- 创建任务；
- 执行测试命令。

工具应该尽量原子化。一个工具只做一类事情，并提供明确的输入输出。不要把“创建教程并绑定文章”写成一个底层工具，因为它包含多个业务步骤，更适合放在 workflow 中。

一个工具定义通常包含：

- name：工具名称；
- description：什么时候使用；
- schema：参数定义；
- riskLevel：风险等级；
- execute：执行函数；
- output：返回结构。

工具层还应该负责参数校验。例如 URL 是否合法、文件是否存在、ID 是否是数字、用户是否有权限访问目标资源。不要把这些校验交给模型自由判断。

### workflows：组织多步骤流程

workflow 负责把多个工具组合成流程。例如“创建 Treasure 标签并补图”不是一个原子工具，而是一个 workflow：

1. 查询标签是否存在；
2. 搜索合适图片；
3. 上传图片到自有素材系统；
4. 创建标签并绑定图片；
5. 查询标签验证结果；
6. 如果需要，加入标签集。

workflow 可以是简单顺序流程，也可以是状态机或图结构。它应该明确每一步的输入、输出、失败处理和验证方式。

把流程放在 workflow 层，而不是写进 prompt，有一个重要好处：流程可以测试，可以复用，也可以在失败后恢复。

### memory：管理短期和长期记忆

memory 目录用于管理 Agent 的记忆系统。短期记忆可以保存当前任务状态，长期记忆可以保存用户偏好和历史经验。

例如用户要求“每篇文章标签不超过 3 个”，这就是一个长期偏好。又比如“treasure article create 需要先创建 draftId”，这是一个工具经验。

记忆系统应该有写入规则，不应该把所有对话都保存下来。还要支持查看、删除、过期和脱敏。

### prompts：管理提示词

提示词应该作为项目资产管理，而不是散落在代码里。prompts 目录可以保存：

- 系统提示词；
- 工具使用说明；
- 输出格式模板；
- 审查提示词；
- 总结提示词；
- 任务拆解提示词。

提示词最好版本化。每次修改都应该知道改了什么、为什么改、影响了哪些评测。

### evals：评测与回归测试

Agent 项目如果没有 evals，很容易越改越不可控。evals 目录可以保存测试用例，例如：

- 创建标签时必须先查重；
- 图片不能直接使用外链，必须上传到自有素材系统；
- 删除操作必须确认；
- 文章正文不能带一级标题；
- 每篇文章标签不能超过 3 个。

这些规则都可以变成评测项。每次改 prompt、工具或 workflow 后跑一遍，能减少回归问题。

### logs：日志和 trace

logs 目录或日志模块用于记录 Agent 的执行过程。至少应该记录：用户目标、计划步骤、工具调用、参数、返回结果、错误信息、用户确认和最终输出。

生产环境中，不一定把日志写到本地目录，也可能写到数据库、对象存储或 observability 平台。但从项目结构上，日志能力应该是独立模块，而不是零散 console。

### config：配置与密钥

config 管理模型配置、工具开关、API Base、权限策略、重试次数和环境变量。

密钥不要写进代码。对于 Agent 项目尤其要注意，因为工具可能访问很多外部系统。配置层应该明确哪些信息来自环境变量，哪些可以写入配置文件，哪些必须通过用户授权获得。

## 一个示例结构

下面是一个简化示例：

~~~text
src/
  agents/
    content-agent.ts
    coding-agent.ts
  tools/
    treasure/
      tag-tools.ts
      article-tools.ts
      material-tools.ts
    filesystem/
      read-file.ts
      write-file.ts
  workflows/
    create-tag-with-image.ts
    create-tutorial-series.ts
  memory/
    preference-memory.ts
    task-state-store.ts
  prompts/
    system.md
    reviewer.md
  evals/
    create-tag.eval.json
    article-style.eval.json
  logs/
    trace.ts
  config/
    model.ts
    permissions.ts
~~~

这个结构的重点是：工具不直接决定业务流程，workflow 不直接写底层 API，Agent 不承载所有实现细节。

## 目录结构和团队协作

当团队多人协作时，清晰结构更加重要。负责工具的人可以维护 tools，负责内容质量的人可以维护 prompts 和 evals，负责平台稳定性的人可以维护 logs 和 config。

如果所有逻辑都在一个 Agent 文件里，任何人修改都可能影响全部能力。模块拆分后，变更边界更清楚，也更容易 code review。

## 常见误区

第一个误区是过早抽象。项目刚开始时不需要设计复杂框架，但至少要避免把工具、prompt 和流程混在一起。

第二个误区是只拆目录，不拆职责。目录很多但每个文件仍然互相调用、互相依赖，复杂度并没有降低。

第三个误区是忽略评测。Agent 项目最容易因为 prompt 改动产生隐性回归，没有 evals 很难发现。

第四个误区是忽略权限。工具目录里如果没有风险等级和权限说明，后续加审批会很痛苦。

## 小结

Agent 项目结构的目标，是让模型能力、工具能力和业务流程分离。agents 负责入口和角色，tools 负责外部能力，workflows 负责任务编排，memory 负责上下文和偏好，prompts 负责语言策略，evals 负责质量保障，logs 负责可观测性。

一个好的结构不会让项目一开始变复杂，而是让复杂度在增长时仍然可控。对于要进入真实业务的 AI Agent，这是非常值得提前设计的基础。

从工程角度拆解 Agent 项目目录结构，理解 tools、workflows、memory、prompts、evals 和 logs 如何分层组织。

AI Agent 实战教程 11：如何设计一个 Agent 项目结构

任务管理助手是理解 AI Agent 的好案例。它看起来简单，只是创建和管理待办，但实际上覆盖了 Agent 的大多数关键能力：意图识别、工具调用、状态管理、授权确认、错误处理和结果验证。

如果能把任务管理助手设计清楚，就可以把同样思路迁移到日历助手、文档助手、代码助手、运维助手和内容管理助手。

## 需求边界

一个任务管理助手可以支持以下能力：

- 创建待办；
- 查询我的任务；
- 标记任务完成；
- 修改截止时间；
- 添加备注；
- 从会议纪要中提取任务；
- 把任务分配给指定人员。

这些功能背后需要访问任务系统 API，也需要知道当前用户是谁、是否有权限、操作是否高风险。

## 工具设计

可以把任务能力拆成多个原子工具：

- 「create_task(summary, due, assignee)」；
- 「list_tasks(status, dateRange)」；
- 「complete_task(taskId)」；
- 「update_task(taskId, fields)」；
- 「add_task_comment(taskId, comment)」；
- 「extract_tasks_from_text(text)」。

不要设计一个过大的 「manage_task」 工具。原子工具更容易描述、校验、授权和审计。

## 意图识别

用户表达通常不是结构化的。例如：

“帮我记一下，明天看一下 Agent 授权逻辑。”

Agent 需要识别出：这是创建任务，任务标题是“看一下 Agent 授权逻辑”，截止时间可能是明天。

如果信息不完整，例如不知道负责人，Agent 可以使用当前用户作为默认负责人，或向用户追问。

## 授权与确认

任务查询通常是低风险操作，可以自动执行。创建任务是写操作，但如果用户明确说“帮我创建一个待办”，可以认为意图明确。

删除任务、批量修改任务、给他人分配任务，则应该要求确认。

授权失败也很常见。比如任务系统缺少写权限，Agent 应该发起授权流程，并在用户完成授权后继续执行，而不是简单报错。

## 状态管理

任务助手必须保存上下文。用户可能说：

“把刚才那个任务标记完成。”

如果系统没有记录刚创建的 taskId，就无法知道“刚才那个”是什么。

需要保存的状态包括：

- 当前用户；
- 最近创建的任务；
- 最近查询结果；
- 用户确认状态；
- 工具调用结果；
- 错误信息。

## 从会议纪要生成任务

更复杂的场景是从会议纪要中提取任务。流程可以是：

1. 读取会议纪要；
2. 提取行动项；
3. 识别负责人和截止时间；
4. 展示给用户确认；
5. 批量创建任务；
6. 返回任务链接。

这里必须加入确认。因为模型提取的负责人和截止时间可能不准确，不能直接批量写入。

## 错误处理

任务系统可能返回多种错误：权限不足、用户不存在、截止时间格式错误、任务 ID 无效、网络超时。Agent 应该把错误转成用户能理解的下一步。

例如权限不足时，不应该只说“API error”，而应该说明需要授权 「task:task:write」，并提供授权流程。

## 结果验证

创建任务后，最好返回结构化结果：

- 任务标题；
- 任务 ID；
- 任务链接；
- 截止时间；
- 负责人；
- 当前状态。

对于关键操作，可以再次查询任务详情，确认状态确实更新。

## 小结

任务管理助手是一个小而完整的 Agent 案例。它展示了 Agent 如何理解目标、调用工具、处理权限、维护状态并验证结果。掌握这个案例后，就能把同样方法扩展到更多真实业务场景。

用任务管理助手案例串联目标理解、工具调用、状态管理、权限确认和结果验证。

AI Agent 实战教程 10：构建任务管理助手

Agent 越能做事，越需要安全、授权和沙箱。一个只能回答问题的模型，风险主要是内容是否准确；一个能读文件、改代码、发消息、删数据、部署服务的 Agent，风险就变成了真实系统风险。

因此，Agent 安全不是上线前才补的功能，而是架构设计的一部分。权限、沙箱、人工确认和审计日志，决定了 Agent 能否在真实环境中可靠运行。

## Agent 安全要回答的问题

设计 Agent 安全机制时，至少要回答几个问题。

第一，Agent 能访问什么资源？例如哪些文件、哪些数据库、哪些 API、哪些用户数据。

第二，Agent 能执行什么操作？读取、创建、更新、删除、发布、发送、部署，这些操作风险完全不同。

第三，谁授权了这些操作？授权是一次性的，还是长期有效的？是否可以撤销？

第四，哪些操作必须人工确认？确认信息是否足够清晰？用户是否知道将发生什么？

第五，操作是否可审计？出问题后能否知道 Agent 做了什么、为什么做、结果是什么？

## 最小权限原则

最小权限原则要求 Agent 只获得当前任务需要的权限。

如果用户只是想查询标签列表，Agent 不应该拥有删除标签的权限。如果用户只是想读取文件，Agent 不应该能写入整个文件系统。

最小权限可以从多个层面实现：

- 工具级权限；
- API scope；
- 文件系统沙箱；
- 网络访问白名单；
- 用户身份隔离；
- 临时授权。

权限越细，系统越安全，但使用成本也会上升。因此需要在安全性和体验之间平衡。

## 沙箱机制

沙箱用于限制 Agent 的运行环境。它可以限制文件读写范围、网络访问、命令执行、环境变量和系统资源。

例如一个代码 Agent 可以被限制只能修改当前工作区文件，不能访问用户 Home 目录。一个内容管理 Agent 可以被限制只能调用查询接口，写入操作需要额外确认。

沙箱的价值不是阻碍 Agent，而是让用户敢于把更重要的任务交给 Agent。

## Human-in-the-loop

Human-in-the-loop 指在关键节点让人参与确认。它适合高风险操作，例如：

- 删除数据；
- 发布文章；
- 修改生产配置；
- 发送邮件或消息；
- 执行部署；
- 进行付费操作；
- 授权访问敏感系统。

确认应该具体，而不是简单问“是否继续”。好的确认会展示操作类型、目标资源、关键参数和潜在风险。

## 授权流程

Agent 授权通常分为两类。

第一类是平台授权，例如 OAuth。用户授权 Agent 访问日历、任务、文档等资源。

第二类是本地执行授权，例如允许 Agent 访问网络、写入某个目录、运行某个命令。

这两类授权经常同时存在。比如一个 Agent 创建飞书待办，既需要飞书 API scope，也需要本地执行环境允许调用 CLI 和访问 keychain。

## 审计日志

审计日志应该记录关键操作：

- 用户请求；
- Agent 计划；
- 工具名称；
- 调用参数；
- 返回结果；
- 用户确认；
- 时间；
- 操作者身份；
- 错误信息。

没有审计日志，Agent 出错后只能猜原因。生产系统必须能复盘。

## 常见安全误区

第一个误区是把权限全交给提示词。提示词可以提醒模型不要做危险事，但不能替代系统级权限控制。

第二个误区是默认信任工具参数。模型生成的参数必须校验。

第三个误区是为了方便关闭确认。短期体验变好了，长期风险会大幅增加。

第四个误区是忽略读取权限。读取敏感数据同样有风险，不只是写操作危险。

## 小结

Agent 安全的目标不是让 Agent 什么都不能做，而是在可控边界内让它放心地做事。最小权限、沙箱、人工确认和审计日志，是 Agent 从演示走向生产的必要条件。

从授权、沙箱、人工确认、审计日志和最小权限原则理解 Agent 安全设计。

AI Agent 实战教程 09：安全、授权与沙箱

MCP（Model Context Protocol）是近几年 Agent 工具生态中非常重要的协议。它试图解决一个现实问题：模型和 Agent 需要连接大量外部系统，但每个系统都单独集成会非常混乱。

如果没有统一协议，一个 AI IDE、一个聊天助手、一个自动化 Agent 都要分别适配文件系统、数据库、浏览器、日历、任务工具、代码仓库等能力。MCP 的思路是把工具、资源和上下文标准化，让不同客户端能够以统一方式连接外部系统。

## MCP 解决什么问题

Agent 要完成真实任务，必须访问外部能力。例如读取文件、查询数据库、搜索文档、创建任务、调用内部 API。问题在于，每个工具的接入方式都不同。

MCP 提供了一个通用接口，让工具提供方实现 MCP Server，Agent 或应用作为 MCP Client 连接它。这样工具可以被多个模型客户端复用。

它解决的是工具生态标准化问题，而不只是一次函数调用。

## MCP 的核心概念

MCP 中常见概念包括 Tools、Resources 和 Prompts。

Tools 是可执行动作，例如搜索文件、创建任务、运行查询。它们通常有输入参数和返回结果。

Resources 是可读取资源，例如文件内容、数据库记录、项目结构、文档列表。它们帮助模型获得上下文。

Prompts 是可复用提示模板，可以把某类任务的最佳实践封装起来。

MCP Server 负责暴露这些能力，MCP Client 负责连接并把它们提供给模型或 Agent。

## MCP 与 Tool Calling 的关系

Tool Calling 和 MCP 经常被放在一起讨论，但它们解决的问题不同。

Tool Calling 关注模型如何选择工具并生成参数。MCP 关注工具如何标准化提供给模型和 Agent。

可以这样理解：

- Tool Calling 是模型侧的调用能力；
- MCP 是工具侧的接入协议；
- Agent 是把模型、工具、状态和权限组合起来的系统。

在实际项目中，MCP Server 暴露工具，模型通过 Tool Calling 选择工具，Agent 框架负责执行和状态管理。

## MCP 的优势

第一，降低集成成本。同一个 MCP Server 可以被多个客户端使用，而不是每个客户端重新写一套集成。

第二，提升工具复用。文件系统、Git、数据库、浏览器、任务系统都可以通过 MCP 复用。

第三，便于权限管理。工具能力可以在 Server 侧做边界控制。

第四，适合构建生态。第三方可以发布自己的 MCP Server，Agent 平台可以按需接入。

## 安全问题

MCP 让工具接入更方便，也意味着风险更集中。一个 MCP Server 可能暴露文件、命令、数据库或内部系统。如果权限不严，Agent 误调用可能造成严重后果。

因此 MCP Server 需要：

- 明确工具风险等级；
- 限制可访问资源；
- 对写操作加确认；
- 记录调用日志；
- 避免暴露敏感凭证；
- 支持用户级权限隔离。

## 适合 MCP 的场景

MCP 适合工具较多、客户端较多、需要复用的场景。例如 AI IDE 读取代码库，企业助手访问内部知识库，运维 Agent 查询监控系统，任务 Agent 操作日历和待办。

如果只是一个简单 API 调用，未必需要 MCP。但当工具生态开始扩张，MCP 的价值会越来越明显。

## 小结

MCP 是连接模型与外部世界的重要基础设施。它不替代 Agent，也不替代 Tool Calling，而是为工具和上下文提供标准化接入方式。理解 MCP，有助于构建可扩展、可复用、可治理的 Agent 工具生态。

理解 MCP 如何统一连接外部工具、资源和上下文，以及它与 Tool Calling 的关系。

AI Agent 实战教程 08：MCP 与工具生态

多 Agent 协作指的是让多个具有不同角色和职责的智能体共同完成任务。它的目标不是简单堆叠多个模型，而是通过分工让复杂任务更清晰、更可控。

在很多真实任务中，单个 Agent 同时负责研究、规划、执行、审查和总结，会导致职责混乱。多 Agent 架构通过角色拆分，把复杂工作流组织成协作系统。

## 为什么需要多 Agent

复杂任务往往包含不同类型的能力。例如生成一份技术方案，可能需要：

- Research Agent 搜集资料；
- Architect Agent 设计架构；
- Coding Agent 编写代码；
- Reviewer Agent 审查风险；
- Writer Agent 整理文档。

这些角色关注点不同。如果全部交给一个 Agent，模型容易在多个目标之间摇摆。拆分角色后，每个 Agent 的提示词、工具和评价标准都可以更明确。

## Supervisor 模式

最常见的多 Agent 架构是 Supervisor 模式。Supervisor 负责理解总体目标、拆分任务、分配给 Worker，并整合结果。

Worker Agent 只负责具体子任务。例如一个 Worker 负责搜索资料，另一个负责生成代码，第三个负责测试。

这种模式的优点是流程清晰。缺点是 Supervisor 的质量非常关键。如果它分配任务不合理，后续结果也会偏离目标。

## Debate 与 Review 模式

有些系统会让多个 Agent 提供不同观点，再由评审 Agent 选择或综合。比如架构设计中，一个 Agent 从性能角度分析，一个从成本角度分析，一个从安全角度分析。

这种模式适合决策类任务，但不适合所有场景。对于简单任务，多 Agent 只会增加成本和延迟。

Review Agent 也很常见。它不参与初始生成，而是负责检查输出，例如代码是否有 bug、文章是否结构完整、方案是否遗漏风险。

## 消息传递设计

多 Agent 协作需要稳定的消息格式。否则一个 Agent 输出的大段自然语言，另一个 Agent 很难准确接住。

推荐消息结构包括：

- 当前任务；
- 已完成工作；
- 关键结论；
- 证据来源；
- 风险和不确定性；
- 下一步建议。

结构化消息能降低误解，也方便记录和调试。

## 工具与权限分配

不同 Agent 不应该拥有相同工具权限。Research Agent 可能只需要搜索和读取；Coding Agent 需要读写代码；Deploy Agent 才可能接触部署能力。

按角色分配工具，可以减少误操作风险。尤其是删除、发布、部署等高风险工具，不应该暴露给所有 Agent。

## 多 Agent 的常见问题

第一个问题是过度设计。很多任务一个清晰工作流就能解决，不需要多 Agent。

第二个问题是循环争论。多个 Agent 互相反馈，但没有明确停止条件，导致成本不断增加。

第三个问题是责任不清。每个 Agent 都在发表意见，却没人负责最终决策。

第四个问题是上下文膨胀。多 Agent 之间传递的信息越来越多，最终影响模型判断。

## 什么时候适合多 Agent

适合多 Agent 的场景通常具备：

- 任务复杂；
- 有明显角色分工；
- 需要审查或多角度分析；
- 执行步骤较长；
- 输出质量比成本更重要。

例如复杂代码迁移、研究报告、产品方案评审、自动化运营流程，都可能适合多 Agent。

## 小结

多 Agent 的核心是职责分工和协作协议，而不是 Agent 数量。设计时要明确谁负责规划、谁负责执行、谁负责审查、谁做最终决策。只有边界清晰，多 Agent 才能提升质量，而不是制造混乱。

理解多 Agent 协作中的角色分工、Supervisor 模式、消息传递、审查与冲突处理。

AI Agent 实战教程 07：多 Agent 协作

Memory 是 AI Agent 能够连续工作的基础。没有记忆，Agent 每次都像第一次见到用户；有了记忆，Agent 才能理解历史、延续任务、保留偏好，并在长期协作中变得更有上下文。

但记忆也是一把双刃剑。保存太少，Agent 不够智能；保存太多，系统会变得混乱，还可能带来隐私和安全风险。因此，Memory 设计的重点不是“尽可能多地记住”，而是“在合适的时候记住合适的信息”。

## 短期记忆

短期记忆通常就是当前对话上下文。它帮助 Agent 理解最近发生了什么。

例如用户刚刚说“把这 10 篇文章整理成教程”，后续又说“绑定到刚才那个模块”，Agent 需要知道“刚才那个模块”指什么。

短期记忆适合保存：

- 当前任务目标；
- 最近对话；
- 工具调用结果；
- 用户刚给出的约束；
- 临时中间产物。

短期记忆的问题是上下文窗口有限。任务越长，历史越多，模型越难关注关键内容。因此长任务需要状态摘要，而不是无限保留所有对话。

## 长期记忆

长期记忆保存跨会话信息，例如用户偏好、项目背景、常用工具、历史决策。

比如用户经常要求“每篇文章标签不要超过 3 个”，这个偏好就可以进入长期记忆。以后创建文章时，Agent 就能自动遵守这个规则。

长期记忆适合保存稳定信息，不适合保存临时情绪、一次性指令或未经确认的敏感数据。

## 向量记忆

向量记忆通常使用 Embedding 和 Vector Database。系统把历史信息转成向量，之后根据当前任务检索相关记忆。

它适合保存大量非结构化内容，例如：

- 历史对话摘要；
- 会议纪要；
- 项目文档；
- 用户反馈；
- 操作经验。

当用户提出新任务时，系统检索相关记忆，把结果放入上下文，帮助 Agent 做出更符合历史背景的判断。

## 记忆写入策略

最容易出问题的是“什么时候写入记忆”。如果每句话都写入，记忆库会很快充满噪音。如果完全不写，Agent 又无法持续学习。

常见策略包括：

- 用户明确说“记住”；
- 系统识别到稳定偏好；
- 任务完成后生成摘要；
- 用户确认后写入长期记忆；
- 对重复出现的信息提升权重。

对于重要记忆，最好让用户可见、可编辑、可删除。

## 记忆读取策略

读取记忆也需要控制。不是每次都读取所有记忆，而是根据当前任务检索相关内容。

例如写 AI Agent 教程时，应该检索用户对文章风格、标签数量、图片来源的偏好，而不需要读取无关的历史任务。

好的读取策略应该考虑相关性、时效性、权限和信息密度。

## 隐私与安全

Memory 可能包含敏感信息，因此必须设计安全边界。

需要考虑：

- 用户是否知道系统记住了什么；
- 用户能否删除记忆；
- 敏感数据是否脱敏；
- 不同用户之间是否隔离；
- Agent 是否会把记忆泄露给不该看到的人；
- 长期记忆是否有过期机制。

没有这些设计，Memory 会从能力变成风险。

## 小结

Memory 让 Agent 更连续、更个性化，也更像一个长期协作伙伴。但记忆系统必须可控、可解释、可清理。真正可靠的 Agent 不会什么都记，而是知道什么值得记、什么时候用、什么时候忘。

了解 Agent 的短期记忆、长期记忆、向量记忆和用户画像，以及记忆系统的风险。

AI Agent 实战教程 06：Memory 记忆机制设计

RAG 是 AI Agent 获得外部知识的重要方式。没有 RAG，Agent 主要依赖模型参数和当前上下文；有了 RAG，Agent 可以查询文档、知识库、数据库和业务资料，从而回答更具体、更实时、更可信的问题。

对于 Agent 来说，RAG 通常不是一个独立应用，而是一个工具。当 Agent 判断自己缺少知识时，就调用检索工具，把相关内容取回，再基于这些内容继续推理或执行任务。

## RAG 的基本流程

RAG 通常包含四个核心步骤。

第一，文档处理。系统把文档、网页、笔记或数据库内容切分成较小片段，也就是 chunks。切分太大，检索不精准；切分太小，语义可能不完整。

第二，向量化。使用 Embedding 模型把每个 chunk 转成向量。向量可以表达文本语义，使系统能根据相似度查找相关内容。

第三，检索。用户提出问题后，系统把问题也转成向量，在向量数据库中找出最相关的 chunks。

第四，生成。系统把检索结果放入模型上下文，让模型基于这些资料生成回答。

## Agent 为什么需要 RAG

Agent 经常要处理具体业务任务，而这些任务需要外部知识。例如：

- 根据公司内部文档回答问题；
- 根据 API 文档生成代码；
- 阅读会议纪要并提取待办；
- 根据产品资料生成教程；
- 查询历史决策记录；
- 从知识库中找出相关案例。

这些知识通常不在模型参数中，即使模型知道一些通用知识，也无法保证和当前业务一致。RAG 可以让 Agent 使用可控知识源。

## Embedding 的作用

Embedding 是 RAG 的基础。它把文本转成向量，使“语义相近”的内容在向量空间里距离更近。

例如用户问“如何让 Agent 调用外部系统”，即使文档里写的是“Tool Calling 用于连接函数和 API”，向量检索也可能找到相关内容。

但 Embedding 不是万能的。它可能找出语义相似但事实不匹配的内容，也可能漏掉关键词强相关的内容。因此生产系统常结合关键词搜索、过滤条件和 rerank。

## 上下文注入的技巧

检索到内容后，不能简单全部塞给模型。上下文窗口有限，内容越多，模型越容易分散注意力。

常见优化包括：

- 只保留 Top K 结果；
- 对结果去重；
- 使用 rerank 重新排序；
- 保留来源信息；
- 对长内容做摘要；
- 按任务类型选择不同检索策略。

对于需要可信答案的场景，最好要求模型基于检索内容回答，并在必要时给出引用。

## RAG 与 Agent 的结合方式

最简单方式是把 RAG 封装成一个工具，例如 「search_knowledge_base(query)」。Agent 在需要知识时调用它。

更复杂的方式是让 Agent 能选择不同知识源。例如产品文档、代码仓库、历史工单、会议纪要分别对应不同检索工具。Agent 先判断问题属于哪个领域，再选择相应工具。

还可以让 Agent 在检索结果不足时自动扩展关键词、调整过滤条件，或者向用户澄清问题。

## 常见问题

第一个问题是检索不到。可能是文档没入库、切分不合理、Embedding 模型不适合、查询改写不充分。

第二个问题是检索到了但用不好。模型可能忽略上下文，也可能把不同来源混在一起，产生不准确结论。

第三个问题是知识过期。文档更新后，如果索引不更新，Agent 会使用旧知识。

第四个问题是权限隔离。不同用户能访问的知识库不同，RAG 必须遵守权限边界。

## 小结

RAG 让 Agent 拥有外部知识，但可靠性来自工程细节：文档切分、Embedding、向量数据库、rerank、上下文组织、引用约束和权限控制。对于企业级 Agent，RAG 往往是从演示走向可用的关键一步。

理解 RAG 如何让 Agent 使用外部知识，掌握检索、Embedding、上下文注入和引用控制。

AI Agent 实战教程 05：RAG 如何增强 Agent

Agentic Workflow 是把 Agent 能力组织成可执行流程的方法。它解决的问题是：当任务不再是一次问答，而是需要多个步骤、多个判断和多个工具时，系统应该如何组织执行过程。

如果没有工作流，复杂任务往往会变成一段超长提示词。模型需要在一次调用里理解所有约束、完成所有步骤、避免所有错误。这种方式很难稳定。Agentic Workflow 的思路是把复杂任务拆成可观察、可控制、可恢复的流程。

## 为什么需要工作流

现实任务通常不是线性的。例如“生成一份竞品分析报告”可能包括：确定竞品范围、搜索资料、提取关键信息、对比功能、总结优劣势、生成报告、检查事实。

这些步骤有依赖关系，也可能出现分支。如果搜索结果不足，需要扩大关键词；如果资料冲突，需要标注不确定性；如果用户要求格式调整，需要重新生成部分内容。

工作流让这些逻辑变得明确，而不是全部交给模型自由发挥。

## Chain 模式

Chain 是最基础的工作流模式。上一步输出作为下一步输入。

例如：

1. 提取用户问题中的关键词；
2. 根据关键词搜索资料；
3. 总结搜索结果；
4. 生成最终回答。

Chain 的优点是简单、稳定、易调试。缺点是灵活性不足，一旦中间步骤失败，后续步骤可能都受影响。

Chain 适合边界明确的任务，比如格式转换、摘要生成、固定流程的数据处理。

## Router 模式

Router 用于根据输入选择不同处理路径。

例如用户请求进入系统后，可以先判断类型：

- 如果是知识问答，走 RAG；
- 如果是代码问题，走代码工具；
- 如果是任务管理，走任务系统；
- 如果是文档总结，走文档解析工具。

Router 的价值是减少无关上下文和工具暴露。模型不需要每次都看到全部工具，只需要看到当前场景相关能力。

## Reflection 模式

Reflection 指的是让模型检查和修正自己的输出。它常用于写作、代码生成、方案设计和长文本总结。

例如生成一段代码后，再让模型检查：是否满足需求、是否有潜在异常、是否需要测试。生成文章后，再检查结构是否完整、是否重复、是否遗漏关键点。

Reflection 可以提升质量，但也会增加成本。它适合高价值输出，不一定适合所有任务。

## Plan-and-Execute 模式

Plan-and-Execute 是 Agent 常见模式。系统先让模型制定计划，再按步骤执行。

例如：

1. 查询是否已有标签；
2. 没有则创建标签；
3. 上传标签图片；
4. 创建文章；
5. 创建教程；
6. 绑定文章；
7. 验证结果。

这种模式适合复杂任务，因为计划可以展示给用户，也可以在执行过程中调整。

## 状态机与图结构

当流程更复杂时，可以使用状态机或图结构来描述工作流。每个节点代表一步操作，每条边代表下一步条件。

LangGraph 这类框架就适合表达这种有状态流程。它可以让 Agent 在不同节点之间跳转，并保留中间状态。

相比纯提示词，图结构更容易调试，也更适合生产环境。

## 常见设计原则

第一，不要让模型一次性做太多事。复杂任务应该拆成多个小步骤。

第二，关键节点要有验证。例如创建资源后再查询一次，确认真的创建成功。

第三，高风险节点要有人工确认。比如删除、发布、发消息、部署。

第四，错误分支要提前设计。不要等错误发生后才让模型临场发挥。

第五，工作流要能恢复。长任务可能中断，系统应该能从上次状态继续。

## 小结

Agentic Workflow 的核心，是把模型的不确定推理放进确定性流程中。好的工作流既保留模型的灵活性，又提供工程系统的可控性。对于真实 Agent 项目，这往往比单纯提升模型能力更重要。

从 Chain、Router、Reflection 到 Plan-and-Execute，理解 Agentic Workflow 的常见模式。

AI Agent 实战教程 04：Agentic Workflow 设计

Tool Calling 是 AI Agent 从“会回答”走向“会执行”的关键能力。没有工具调用，模型只能生成文本；有了工具调用，模型才能访问外部系统，完成搜索、查询、写入、计算、文件处理、任务创建等真实动作。

很多 Agent 项目的第一步，都是把业务能力封装成工具。工具设计得越清晰，Agent 越稳定；工具设计得越模糊，模型越容易误用。

## Tool Calling 的基本过程

Tool Calling 通常包含四个角色：用户、模型、工具描述和工具执行器。

用户提出目标，例如“帮我查一下某个标签是否存在”。模型根据上下文判断需要调用查询工具。工具描述告诉模型这个工具叫什么、能做什么、需要哪些参数。模型生成结构化参数后，系统执行工具，并把结果返回给模型。

模型本身不会真的访问数据库或执行命令。它只是生成一个“调用意图”。真正执行的是宿主系统。因此，Tool Calling 是模型推理能力和外部系统能力之间的桥梁。

## 工具 schema 为什么重要

工具 schema 是模型理解工具的主要依据。一个好的 schema 应该包含：

- 工具名称；
- 工具用途；
- 参数名称；
- 参数类型；
- 必填字段；
- 返回值结构；
- 使用限制；
- 风险说明。

比如一个创建任务工具，不应该只写“创建任务”。它应该说明 summary 是任务标题，due 是截止时间，assignee 是负责人 ID，返回值包含 taskId 和 url。

如果 schema 太模糊，模型可能传错参数、漏掉必填字段，或者在不该调用时调用。

## 工具应该尽量原子化

工具设计有一个重要原则：单个工具最好只做一类明确事情。

例如不要设计一个巨大的工具叫 「manage_task」，里面既能创建任务、删除任务、查询任务、修改负责人、上传附件。这样的工具对模型来说难以选择，对系统来说也难以做权限控制。

更好的方式是拆成：

- 「create_task」
- 「list_tasks」
- 「update_task」
- 「complete_task」
- 「delete_task」

这样每个工具的风险等级更清晰，也方便分别加确认机制。

## 读工具与写工具

Tool Calling 最大的风险来自写操作。读取数据通常风险较低，例如查询标签、获取文章、查看日程。但写操作可能改变系统状态，例如创建文章、删除数据、发送消息、修改配置。

因此工具可以按风险分层：

- 低风险：查询、读取、搜索；
- 中风险：创建草稿、上传文件、更新非关键字段；
- 高风险：删除、发布、发消息、部署、支付、修改权限。

低风险工具可以自动执行，高风险工具必须让用户确认。这个规则不应该只依赖模型判断，而应该由系统强制执行。

## 参数生成与校验

模型生成的参数不能直接信任。系统需要校验参数是否合法。例如：

- ID 是否是数字；
- URL 是否是合法在线资源；
- 文件路径是否存在；
- 日期格式是否正确；
- 枚举值是否在允许范围；
- 用户是否有权限操作目标资源。

工具执行器应该在调用真实系统前做校验，并返回结构化错误。这样模型才能根据错误修正下一步。

## 工具返回值设计

工具返回值也很重要。返回值应该尽量结构化，而不是只返回一段自然语言。

例如创建任务后，返回：

- taskId；
- title；
- url；
- status；
- createdAt。

这样 Agent 可以继续引用结果。用户说“把刚才那个任务标记完成”时，系统可以根据 taskId 执行，而不是重新猜测。

## 常见问题

第一个问题是工具太多。工具越多，模型选择错误的概率越高。可以通过工具分组、路由、按场景加载来降低复杂度。

第二个问题是工具描述不准确。模型会按描述使用工具，如果描述和真实行为不一致，就会产生错误调用。

第三个问题是缺少确认机制。很多演示系统可以自动删文件、自动发消息，但生产系统绝不能这样设计。

第四个问题是工具返回不可解析。返回一大段日志给模型，远不如返回结构化 JSON。

## 小结

Tool Calling 是 Agent 工程的核心能力。它让模型连接真实系统，但可靠性来自清晰 schema、原子工具、参数校验、结构化返回和权限控制。工具不是越多越好，而是越清晰、越可控越好。

学习 Tool Calling 的基本原理：工具 schema、参数生成、调用执行、结果回传与安全边界。