Agent

Agent 的核心不是“模型很聪明”，而是让模型在受控边界内调用工具、读取状态、执行步骤，并根据结果继续决策。

先区分 Agent、Workflow 和 Chatbot

很多系统被叫作 Agent，但复杂度并不一样：

如果流程非常固定，优先用 workflow。只有当任务需要根据中间结果动态决策时，Agent 才更有价值。

Agent 和普通聊天的区别

普通聊天主要依赖模型已有能力和当前上下文。Agent 则会连接外部工具，例如搜索、数据库、文件系统、日历、邮件、浏览器、代码执行环境等。

更直白地说：

• Chatbot 主要负责回答
• RAG Chatbot 主要负责基于资料回答
• Agent 不只回答，还会选择工具并执行步骤

Agent 基本组成

Agent 的核心循环

可以把 Agent 理解成一个循环：

观察当前状态
  -> 判断下一步
  -> 调用工具或回答
  -> 读取结果
  -> 更新状态
  -> 判断是否完成

这个循环必须有终止条件。否则模型可能不断搜索、不断调用工具，既浪费成本，也可能产生危险操作。

一个 Agent 的执行过程

用户目标
  -> 理解任务
  -> 判断是否需要工具
  -> 调用工具
  -> 阅读工具结果
  -> 决定下一步
  -> 直到完成或请求用户确认

例子：用户说“帮我总结这个仓库最近一周改了什么”。

Agent 可能会：

• 调用 git log 查看提交。
• 调用 git diff 查看变更。
• 按功能、修复、文档分类。
• 生成摘要。
• 如果发现信息不足，继续读取相关文件。

适合做 Agent 的任务

• 多步骤资料搜索和总结
• 自动生成周报、日报、会议纪要
• 代码库阅读和修改
• 表单填写和业务流程自动化
• 数据分析和报告生成
• 内部工具统一入口

判断是否需要 Agent

可以用这几个问题判断：

• 任务是否需要多步骤？
• 中间结果是否会影响下一步？
• 是否需要调用外部工具？
• 是否允许模型在多个合法动作中选择？
• 失败后是否可以恢复或请求用户确认？

如果答案大多是“否”，普通 LLM 调用或固定 workflow 可能更简单、更稳定。

不适合直接交给 Agent 的任务

• 高风险资金操作
• 没有权限边界的数据访问
• 需要强确定性的核心交易流程
• 失败成本极高且无法人工复核的操作

项目检查点

• 工具 schema 是否清晰
• 工具调用是否有权限控制
• 高风险操作是否需要用户确认
• 是否能从失败中恢复
• 是否记录完整执行轨迹
• 是否有最终完成条件，而不是无限循环

工具设计原则

工具不是越多越好。好的工具应该：

• 名称清晰，让模型知道什么时候用
• 参数结构化，避免自然语言乱传
• 返回结果简洁，不要塞太多无关内容
• 对危险操作有确认机制
• 对错误给出可恢复的信息

坏工具示例：

do_everything(input: string)

好工具示例：

search_documents(query: string, limit: number, department?: string)

工具返回结果怎么设计

工具返回给模型的内容不应过长，也不应只返回机器难以理解的原始数据。建议包含：

• status：success、error、needs_confirmation。
• summary：给模型阅读的简短摘要。
• data：结构化结果，方便继续处理。
• next_actions：可选的下一步建议。
• error_message：失败时说明可恢复方式。

示例：

{
  "status": "success",
  "summary": "找到 3 个相关文档片段，最相关的是员工手册第 4 章。",
  "data": [
    {
      "title": "员工手册",
      "section": "第 4 章 年假",
      "snippet": "入职满一年后享有年假..."
    }
  ]
}

好的工具结果能减少模型误读，也能让后续步骤更稳定。

权限和确认

工具可以分成几类：

不要把“请谨慎操作”只写在 Prompt 里。高风险操作必须由代码层确认。

Agent 常见失败模式

• 工具太多，模型选择困难
• 工具返回内容太长，模型抓不住重点
• 没有终止条件，循环调用
• 缺少权限控制，越权读取数据
• 缺少用户确认，自动执行高风险操作
• 没有日志，失败后无法复盘

Agent 评测

Agent 不能只评测最终回答，还要评测过程：

• 是否选择了正确工具。
• 工具参数是否合理。
• 是否遵守权限和确认规则。
• 失败后是否能恢复。
• 是否在完成后停止。
• 最终结果是否满足用户目标。

建议保存完整 trace，包括每次模型输入、工具调用、工具结果和最终回答。没有 trace，就很难调试 Agent。

实战练习

• 设计一个只读文档搜索工具的 schema。
• 设计一个需要确认的“发送邮件”工具 schema。
• 写出 Agent 在“生成周报”任务中的执行步骤和终止条件。
• 为一个 Agent 任务准备 10 条评测用例，包括工具失败和权限不足场景。