Wiki Notes

Appearance

01. 基础与边界 ​

版本：v1.1

最后更新：2026-07-09

适用对象：刚开始学习 Agent、准备把工作流升级成 Agent、或正在判断某个业务到底该不该进入 Agent 化的产品、研发、平台工程与技术负责人

1. 为什么先学“边界”，再学“实现” ​

学习 Agent 最容易犯的错误，是一开始就追着框架和 Demo 跑，但没有先回答一个根本问题：

  • 这个问题到底需不需要 Agent？

如果你连边界都没建立，就会出现两个典型问题：

  • 把所有多步骤任务都叫做 Agent
  • 把本该用固定工作流解决的问题做成高成本、不稳定的动态系统

所以，真正的第一课不是 API，而是判断。

2. 什么是 AI Agent ​

一个实用定义：

  • AI Agent 是一个以 目标 为中心，能 感知上下文、调用外部工具、根据执行反馈继续调整行为，并在必要时 维护状态 的系统。

这个定义里最关键的是 4 个词：

  • 目标
  • 工具
  • 反馈
  • 状态

如果系统只是在单轮对话里生成一段回答，它通常只是 LLM 应用，而不是完整意义上的 Agent。

3. Agent 与普通 LLM 应用的区别 ​

普通 LLM 应用 ​

常见流程：

  1. 用户输入问题
  2. 模型生成回答
  3. 应用展示结果

常见任务：

  • 总结
  • 改写
  • 翻译
  • 分类
  • 信息抽取

Agent ​

常见流程：

  1. 用户给出目标
  2. 系统判断是否需要调用工具
  3. 系统选择搜索、检索、代码、数据库或业务 API
  4. 系统读取结果
  5. 系统决定下一步是否继续
  6. 系统最终交付结果

常见任务：

  • 研究助手
  • 企业知识库助手
  • 工单分流与处理
  • 自动化报表与分析
  • 代码修复或代码审查

4. 什么不算 Agent ​

下面这些能力本身不应被夸大为 Agent：

  • 单次 Prompt 输出
  • 只有一个固定调用链的脚本
  • 没有状态和反馈循环的函数拼接
  • 单次 RAG 问答
  • 普通聊天机器人

注意：

  • RAG 不等于 Agent
  • 工具调用 也不自动等于 Agent

只有当系统真正具备“围绕目标做多步动态决策”的特征时，才更接近 Agent。

5. 什么时候不该用 Agent ​

这是最重要的一节。

场景 1：任务路径稳定 ​

如果流程总是：

  1. 读输入
  2. 查固定数据源
  3. 生成固定格式输出

那么大概率更适合工作流，而不是 Agent。

场景 2：不需要动态选择工具 ​

如果你非常确定：

  • 总是查同一个接口
  • 总是读同一种文档
  • 总是输出同一模板

就不必给模型太多“自由”。

场景 3：风险很高但收益不明显 ​

例如：

  • 写数据库
  • 发邮件
  • 创建工单
  • 操作财务系统

如果只是为了“看起来智能”，就让模型直接决策高风险动作，这通常是不划算的。

场景 4：业务目标是稳定性，不是探索性 ​

固定流程通常：

  • 更便宜
  • 更快
  • 更可测
  • 更可控

对于很多企业业务，这是更优解。

6. 什么时候该用 Agent ​

场景 1：任务需要多步探索 ​

例如：

  • 搜多个来源
  • 比较多个结果
  • 根据中间结果决定下一步

场景 2：任务依赖外部环境 ​

例如：

  • 实时搜索
  • 文件系统
  • 数据库
  • 浏览器操作
  • 代码执行

场景 3：任务目标清晰，但路径不固定 ​

例如：

  • “帮我找出这个问题的根因，并给出建议”
  • “帮我基于这些文档做调研”
  • “帮我把用户请求分类并分派到合适处理链路”

场景 4：需要人机协作 ​

例如：

  • 先做草稿，再给人审批
  • 先查证据，再交由人工确认是否执行

7. 工作流与 Agent 的关系 ​

很多人会把它们当作对立关系，其实不是。

更好的理解是：

  • 工作流：路径大多由代码预先决定
  • Agent：路径在运行中由模型部分决定

两者经常是混合使用的。

一个现实系统很可能长这样：

  1. 固定工作流负责总体流程
  2. 某些节点交给 Agent 做动态决策
  3. 高风险节点必须人工审批

根据 LangGraph 官方文档在 2026-07-01 可访问的说明：

  • workflows 更适合预设路径
  • agents 更适合动态决定流程和工具使用

这也是最实用的区分方式。

8. Agent 的价值到底在哪里 ​

Agent 的价值不在于“让模型更像人”，而在于：

  • 把模型从“只会说”变成“会做事”
  • 把模型从“单轮输出”变成“围绕目标完成任务”
  • 把模型从“内容生成器”变成“系统里的决策节点”

但请记住：

  • 价值来自 正确接入系统
  • 不是来自 无约束的自主性

9. 先分清“增强型 LLM 应用”“工作流”“Agent” ​

根据 Anthropic 官方《Building Effective AI Agents》在 2026-07-07 可访问的说明，一个很重要的判断前提是：

  • 不要把所有带工具的系统都叫 Agent

更实用的分层理解通常是：

形态核心特征更适合什么
增强型 LLM 应用一次模型调用，外加检索、模板、函数调用等增强摘要、问答、结构化抽取
工作流路径大体由代码预定义，局部节点可用模型判断路径稳定、需要可控自动化的业务流程
Agent模型在目标约束下动态决定步骤、工具和下一步动作路径不固定、依赖多轮反馈与环境交互的任务

这层区分非常关键，因为它决定了：

  1. 你后面是该优先做 Prompt，还是先做状态机。
  2. 你需要的是一次调用优化，还是长期运行治理。
  3. 你要不要为审批、恢复、租约、轨迹评测付出额外复杂度。

10. Agent 不是二元判断，而是自治等级问题 ​

很多系统并不是“是 Agent”或“不是 Agent”这么简单，更现实的视角是：

  • 它到底把多少决策权交给了模型

可以把自治程度粗分成四档：

第 1 档：单次调用 ​

  • 模型只生成一次输出
  • 没有显式工具循环
  • 没有任务状态推进

第 2 档：单次调用 + 工具 ​

  • 模型可以请求一个或少数几个工具
  • 应用负责绝大多数编排
  • 更像增强型 LLM 应用

第 3 档：工作流 + 动态节点 ​

  • 主流程由代码固定
  • 局部节点让模型做路由、检索、摘要、草稿生成等决策
  • 这是企业里非常常见、也非常实用的一档

第 4 档：长循环 Agent ​

  • 模型能围绕目标多轮推进
  • 会读取环境反馈并调整后续动作
  • 需要明显更强的状态、审批、恢复和观测设计

根据 OpenAI Agents SDK quickstart 与 Building agents 学习路线在 2026-07-07 可访问的说明，官方也强调从一个聚焦 Agent 起步，而不是一开始就设计复杂自治系统。

11. 一条足够实用的选型规则 ​

可以按下面顺序判断：

  1. 单次模型调用能不能解决？
  2. 单次模型调用加固定工具能不能解决？
  3. 固定工作流加少量动态节点能不能解决？
  4. 如果前三者都不够，再考虑 Agent。

根据 OpenAI 官方 Agents SDK 指南在 2026-07-01 的说明：

  • 当 one model call + tools + application-owned logic 足够时，优先考虑 Responses API
  • 当应用要自己管理 orchestration、tool execution、approvals、state 时，再考虑 Agents SDK

这条建议非常适合作为实际选型基准。

12. 决定是否上 Agent 时，至少先过四道门 ​

在真实项目里，建议把“要不要上 Agent”拆成四个检查问题：

12.1 任务真的存在路径不确定性吗 ​

如果每一步基本都能提前写死，那么工作流通常更划算。

12.2 动态决策带来的收益，能覆盖额外复杂度吗 ​

Agent 带来的不是免费的智能，而是新的工程面：

  • 更多状态
  • 更多失败模式
  • 更多审批点
  • 更多评测成本

12.3 任务里是否包含明显高风险副作用 ​

如果任务会：

  • 改数据
  • 发消息
  • 改权限
  • 触发资金、生产、合规动作

那你需要的不只是“让模型更会想”，而是整套治理能力。

12.4 人工是否真的愿意接住它的异常 ​

很多团队会低估人机协作的成本。Agent 一旦进入生产，常常不是“自动跑成功”，而是：

  • 一部分自动完成
  • 一部分进入审批
  • 一部分进入人工纠偏

如果后面根本没人接，那自治程度越高，反而越危险。

13. 一个简单但很有效的收益-风险判断法 ​

可以用一个非常务实的二维判断：

维度低高
路径不确定性固定处理链即可需要动态规划、重试和探索
副作用风险主要是读和分析会触发写操作、审批、外部状态变化

四象限里最值得上 Agent 的，通常是：

  • 路径不确定性高
  • 但可以先把副作用限制在低风险读操作

最不该一上来就做高自治 Agent 的，通常是：

  • 路径并不复杂
  • 但副作用风险极高

这种任务更适合：

  • 显式工作流
  • 人工审批
  • 局部模型辅助

14. Agent 真正难的不是“会不会调用工具”，而是“会不会停” ​

对初学者来说，一个非常容易忽略的边界问题是：

  • 系统什么时候该结束
  • 什么时候该升级给人工
  • 什么时候该承认自己不确定

根据 OpenAI Running agents 文档在 2026-07-07 可访问的说明，运行时不只是把 Agent 跑起来，还要设计对话状态策略、流式输出、工具执行与后续续接方式。放到工程里，这本质上要求你定义停止条件，而不是默认让循环自己“想停就停”。

至少建议明确三类停止信号：

  1. 目标已满足。
  2. 已经缺少继续前进所需的关键证据。
  3. 已经触发风险、成本或审批阈值。

如果这三类信号都没有被定义，系统通常会出现：

  • 无意义多轮调用
  • 工具乱试
  • 成本上涨
  • 幻觉式继续执行

15. 很多“需要 Agent”的问题，其实先用工作流就能解 ​

Anthropic 在《Building Effective AI Agents》里很强调一个非常重要的现实：

  • 很多成功系统起点不是全自治 Agent，而是简单、可组合的 workflow

这条经验非常值得初学者记住，因为它能帮你避开一个常见误区：

  • 还没把任务拆清楚，就先去追求多 Agent 和自主性

更好的顺序通常是：

  1. 先把输入、输出和约束写清楚。
  2. 先把固定部分 workflow 化。
  3. 先把高风险部分留给人工或规则。
  4. 只有在固定路径明显不够时，再给局部节点更大自由度。

这样做的好处是，你能更早获得：

  • 可观测性
  • 可回归性
  • 审批边界
  • 成本基线

16. 初学者必须建立的 5 个认知 ​

  1. Agent 不是“更高级的聊天机器人”。
  2. Agent 的难点不是 Prompt，而是系统设计。
  3. 工具设计质量，往往比模型多强更关键。
  4. 状态、审批、评测和日志，是生产化的核心。
  5. 很多系统最终会是“工作流 + Agent”的混合模式。

17. Agent 至少要拆成哪四层 ​

很多入门材料会把 Agent 讲成一句话：

  • “模型会自己想、自己调工具、自己完成任务”

但真正落地时，更有用的拆法通常是四层：

  1. 目标层：到底要完成什么、成功标准是什么。
  2. 能力层：它拥有哪些工具、知识源、审批入口和可调用服务。
  3. 运行时层：谁负责状态、重试、暂停、恢复、流式输出与轨迹。
  4. 治理层：谁负责风险分级、批准、日志、评测与发布门禁。

如果这四层不拆开，你很容易把所有问题都误归因成：

  • “模型不够聪明”

但现实里很多失败其实来自：

  • 工具太模糊
  • 状态没有持久化
  • 没有定义暂停与恢复
  • 高风险动作没有审批
  • 运行轨迹无法复盘

这也是为什么 OpenAI 当前 Agent definitions、Running agents、Guardrails and human review、Integrations and observability 都分别成章，而不是只给一个“调用模型 + 工具”的例子。

18. 先分清“模型上下文”和“运行时上下文” ​

这是做 Agent 最容易混掉、但一旦混掉后面会越来越乱的一条边界。

根据 OpenAI 当前 Agent definitions 文档，一个非常关键的实践是：

  • model context 是给模型看的
  • local context / runtime context 是给应用运行时看的

更直白地说：

  • 用户问题、任务目标、检索结果、需要模型判断的事实，应进入模型上下文
  • 数据库连接、登录态、内部服务 client、审批人信息、日志器、运行时依赖，通常不该直接塞进模型上下文

如果这层边界不清楚，常见后果会是：

  • prompt 里塞进太多不该给模型的内部实现细节
  • token 飙升，但决策质量没有明显变好
  • 权限和身份信息被不必要地暴露给模型
  • 工具执行与业务状态耦得很死，后面很难审计

所以一个更成熟的判断方式通常是：

  • 模型需要知道，才能决定下一步 的，才进入模型上下文
  • 系统自己需要知道，才能安全执行 的，优先保留在运行时上下文

19. Tool calling 只是入口，真正难的是工具契约 ​

很多团队看到模型能调工具，就觉得 Agent 已经成型了。

但 Anthropic 当前关于 writing tools for agents 的经验和 OpenAI 当前 Using tools 的组织方式，其实都在强调同一个事实：

  • 工具不是“能调就行”，而是要有清晰契约

一个真正适合给 Agent 用的工具，至少要回答清楚：

  • 它解决什么问题
  • 什么时候该调，什么时候不该调
  • 输入字段到底是什么意思
  • 返回结果哪些是证据，哪些只是状态
  • 会不会有副作用
  • 失败后该怎么重试、回退或升级

19.1 一个差工具长什么样 ​

  • 名字很泛，例如 process_data
  • 入参很多，但字段语义含糊
  • 输出是一大段自由文本，应用层很难消费
  • 没说清楚副作用，例如是否会写库、发消息、改权限
  • 没有错误类型或状态码，失败后只能让模型“猜”

19.2 一个更适合 Agent 的工具长什么样 ​

  • 名字表达单一意图，例如 search_invoice_records、draft_refund_reply
  • 参数边界明确，少而准
  • 输出里能区分 evidence、status、next_action_hint
  • 对副作用有显式标注
  • 对失败与不可执行场景有清晰返回

如果工具契约没有设计好，Agent 很容易表现成：

  • 看起来会调很多工具
  • 实际上每一步都在试错和误解

20. 多 Agent 不是默认更高级，很多时候只是把复杂度拆散 ​

“要不要多 Agent”也是非常容易被说粗的地方。

根据 OpenAI 当前 Orchestration and handoffs 文档，一个很有用的判断是先区分两种协作：

  • agents as tools
  • handoffs

20.1 Agents as tools ​

这种模式更像：

  • 主 Agent 仍然负责最终结果
  • 专项 Agent 只是作为能力组件被调用

它更适合：

  • 你想保留一个主负责人
  • 只是让某些子能力专业化，例如总结、检索、代码修复、风险审查
  • 你希望轨迹上仍然能看出“主流程是谁在驱动”

20.2 Handoffs ​

handoff 更像：

  • 当前负责者真的把任务转交给另一个更合适的 Agent
  • 后续由另一个 Agent 主导该阶段

它更适合：

  • 阶段职责边界明显不同
  • 审批策略、工具面、输出风格完全不同
  • 你需要在轨迹上看到显式的责任切换

20.3 为什么不该默认一上来就多 Agent ​

多 Agent 带来的不只是“更聪明”，还会带来：

  • 更多路由决策
  • 更多状态同步
  • 更多责任边界
  • 更多评测路径
  • 更多失败组合

所以更稳的顺序通常是：

  1. 先把单 Agent 跑通。
  2. 先证明单 Agent 的瓶颈真来自职责过宽。
  3. 再拆成 specialist，而不是为了“听起来高级”先拆。

21. MCP、函数调用、连接器都不是 Agent 本体 ​

现在很多团队学 Agent 时，又会把另一个概念混进去：

  • 只要接了 MCP / connectors / tools，就是 Agent

这也不对。

根据 OpenAI 当前 Using tools、Integrations and observability 文档，以及 MCP 官方规范，MCP 更准确的定位是：

  • 一种把外部工具和上下文接进模型系统的协议 / 接口层

它解决的是：

  • 怎么暴露工具
  • 怎么传 schema
  • 怎么做连接、认证与调用

它不直接解决：

  • 任务是否该自治
  • 何时停止
  • 谁来审批
  • 多步状态怎么推进
  • 失败后怎么恢复

所以更准确的理解应该是：

  • MCP 是 Agent 能力接入层的一种标准化方式
  • 不是“用了 MCP 就天然更像 Agent”

22. 真正决定 Agent 成败的，往往是停止条件与升级条件 ​

很多 Demo 会重点展示：

  • 会不会搜
  • 会不会调工具
  • 会不会自动继续下一步

但真正到生产里，常常更重要的是：

  • 什么时候该停
  • 什么时候该交给人
  • 什么时候该承认“缺少证据”

OpenAI 当前 Running agents、Guardrails and human review 文档都在提醒一件事：

  • 运行时要能继续，也要能暂停、审查、恢复或终止

一个更可执行的停止 / 升级设计，至少建议有这几类信号：

信号更像什么情况推荐动作
goal_reached目标已经满足结束并产出结果
missing_evidence缺关键证据，继续搜也不稳追问、拒答或转人工
side_effect_threshold即将执行高风险动作进入审批
retry_exhausted工具或环境多次失败停止自动重试并升级
budget_exceededtoken、时间或费用超预算终止或降级路径
policy_blocked命中安全或合规约束拒绝、屏蔽或人工复核

如果这些信号没有被产品化，系统通常会停留在：

  • “能跑”

但达不到：

  • “能安全地长期跑”

23. 初学者最值得先做的，不是多 Agent，而是第一版运行时骨架 ​

在官方文档和大量工程经验里，有一个共识经常被忽略：

  • 第一版最该先补的是 runtime skeleton，而不是炫技型自治

一个足够实用的第一版骨架，通常至少包括：

  • 一个主 Agent
  • 一组边界清楚的工具
  • 明确的输入 / 输出 contract
  • 对话或任务状态保存策略
  • 审批或人工 review 入口
  • 工具调用与模型调用 trace
  • 基础评测样例

这比一开始就追求：

  • 多 Agent 互相讨论
  • 长链条自治循环
  • 看起来很“像人”的行为

通常更接近真实可交付系统。

24. 重点官方资源 ​

以下资源已按 2026-07-09 复核到当前正式入口；其中部分 OpenAI 页面对脚本访问会返回 403，但浏览器入口仍可正常打开：

25. 这一章学完后，你应该能回答的问题 ​

  1. 什么是 Agent？
  2. 什么情况下不该用 Agent？
  3. RAG 和 Agent 的关系是什么？
  4. 为什么固定工作流有时比 Agent 更好？
  5. 为什么很多问题的难点不在模型，而在工具契约与运行时？
  6. model context 和 runtime / local context 为什么必须分开？
  7. 什么情况下该用 agents as tools，什么情况下才该用 handoff？
  8. 为什么接了 MCP 也不代表系统已经成了 Agent？
  9. OpenAI 为什么建议很多场景先用 Responses API？

如果这 9 个问题你能独立回答，这一章就算真正掌握了。