AI Agent 工程化实战指南
引言
近期花些时间看了下几家的AI白皮书,并让AI整理了一下,提取些值得记录的内容。
文档说明:本文档完整整合了 Anthropic、OpenAI、12-Factor、Manus、Cognition、阿里等机构的工程实践。包含原始提取的全部表格与细节,并附带了针对官方原文深度核查后的专家按语。建议作为团队内部的主干 Wiki 文档沉淀。
第一篇:核心共识(01-核心共识.md)
六条结论在 Anthropic、OpenAI、12-Factor、Manus、Cognition、阿里手册中反复出现。
每条固定五段:结论 -> 因果链 -> 反例 -> 检查项 -> 来源。读结论句即可,展开按需。
共识 1: Agent 的骨架只有四件东西
结论
Agent = 模型 + 工具 + 循环 + 停止条件。其余全部是围着这四个零件做的工程约束。
因果链
模型本身只会生成文本;要让它“做事”,必须给它可调用的外部能力(工具),并允许它在拿到工具结果后再次决策(循环)。循环必须有终止判断,否则模型会无限重试或提前宣布完成(停止条件)。四者缺一,都不是 Agent:缺工具是聊天机器人,缺循环是一次函数调用,缺停止条件是不可控进程。
反例
- 把“多轮对话”当成 Agent:没有工具调用,只是上下文变长。
- 有工具但没有停止条件:模型连续调用同一工具十余次,账单上涨而任务未完成。
- 停止条件写成“模型说完成了”:模型在失败时同样会说完成,属于自证。
检查项
- 能否用一张图画出「输入 -> 模型决策 -> 工具调用 -> 结果回填 -> 再决策 -> 终止」?
- 停止条件是外部可验证的,还是模型自述的?
- 工具调用失败时,循环是重试、降级还是终止?是否显式定义?
来源
Anthropic《Building Effective Agents》提出 agent 为“LLM 在循环中使用工具”;OpenAI 实践指南写作 model + tools + instructions;Google 白皮书写作 model + tools + orchestration;阿里手册写作 Model + Harness。四者骨架一致,仅命名不同。
共识 2: 第一个决策不是技术选型,而是“该不该用 Agent”
结论
如果任务路径可以预先枚举,用 workflow;只有当路径必须由模型在运行时决定时,才用 Agent。
因果链
Agent 的每一步决策都是概率性的,带来三类成本:不确定性(同一输入不同路径)、验证成本(无法用固定断言验收)、运行成本(多轮模型调用)。路径可枚举时,这些成本没有换来任何收益,只是把确定性流程变成不确定流程。反过来,路径无法枚举时(开放输入、工具结果不可预知、需要临场调整),workflow 会退化成大量 if-else,维护成本高于 Agent 的不确定性成本。
反例
- 用 Agent 做固定字段抽取:明明一条规则或一次结构化输出即可,却引入循环与重试。
- 用 Agent 做固定审批流:审批节点、顺序、权限都写在制度里,Agent 只是在复述规则。
- 反过来,用 workflow 处理开放式客服:分支爆炸,最终仍然要靠模型兜底。
检查项
- 把任务的主干路径画出来,分支数是否可枚举(≤ 一个屏幕)?
- 失败一次的业务代价是多少?能否承受概率性失败?
- 是否存在“必须先看工具返回,才知道下一步”的环节?有则倾向 Agent,无则倾向 workflow。
来源
Anthropic 明确把“先用最简单的方案”作为第一原则,并区分 workflow 与 agent;OpenAI 给出“何时该构建 Agent”的判断条件(复杂决策、规则难维护、非结构化输入)。两家结论一致。
💡 深度核查与专家按语:真实生产系统通常是混合架构(Hybrid)。核心不可逆环节用 Workflow 锁定确定性,边缘探索环节用 Agent 处理不确定性。但需注意:混合的代价是 Harness 复杂度上升,如果画不清控制流归属,请退回纯 Workflow。
共识 3: 所有工程复杂度只来自三个问题
结论
上下文(这一刻模型该看见什么)、状态(进程结束后任务在哪里)、验证(凭什么说做对了)。其余问题都可以归到这三类。
因果链
- 上下文决定单步质量:给了多余注意力,给少了缺关键信息,给错了直接误导。
- 状态决定任务能否跨越请求、进程与故障:不持久化,重启即丢;不统一,业务状态与执行状态会分叉。
- 验证决定能否收敛:没有外部判据,循环无法停止,改进也无法度量。
- 这三个问题不解决,模型再强也只是“单次表现好”;解决之后,模型换代才有稳定收益。
反例
- 只优化提示词,不解决状态:压测时任务丢失、重复执行、无法归因。
- 只做 RAG,不做上下文裁剪:检索内容越多,模型越容易忽略真正的指令。
- 只看最终答案,不看执行轨迹:答案碰巧正确,但调用了不该调用的工具。
检查项
- 上下文是“编译”出来的(按任务裁剪、排序、压缩),还是把历史全量拼接?
- 状态是否外置并可序列化?进程重启后能否从断点继续?
- 是否存在一个不依赖模型的完成判据(测试、比对、人工确认)?
来源
Anthropic 的 context engineering 系列、Manus 的上下文工程实践、12-Factor 的“自有上下文 / 统一执行状态”、阿里的“状态外置”。指向同一组问题。
共识 4: 瓶颈通常在 Harness,不在模型
结论
换更强的模型能解决一部分问题,但上下文组织、任务状态、工具校验、失败恢复这些 Harness 层的缺口,换模型解决不了。
因果链
模型负责“理解与决策”,Harness 负责“把决策变成可靠执行”。同一模型在两种 Harness 下表现差异,往往大于两个模型在同一 Harness 下的差异。原因很直接:模型输出是概率性的,而 Harness 是确定性的;把不确定性收敛在 Harness 里,系统才稳定。反之,把本应由 Harness 承担的职责(校验、重试、状态)推给模型,等于要求概率系统自我保证。
反例
- 模型答错就换模型,却不校验工具返回的字段是否缺失。
- 任务中断就加重试,却不在重试前恢复状态,导致重复写入。
- 效果不好就加长提示词,却不减少无关上下文,反而稀释了指令。
检查项
- 最近三次线上问题,归因到模型的有几次?归因到上下文/状态/校验的各几次?
- 工具返回是否有 schema 校验与异常分支?
- 失败后是否有恢复路径,而不是从头再来?
来源
Anthropic 与阿里手册均明确把 Model 与 Harness 的责任边界分开;12-Factor 进一步把“控制流、上下文、状态”划归应用侧自有,而非交给框架隐式处理。
💡 深度核查与专家按语:不要将 LLM 绝对化地视为“不可靠内核”,它是“能力很强但输出概率性的推理引擎”。Harness 的职责不是否定其能力,而是将其不确定性收敛到可接受范围。
共识 5: 可靠性来自“约束不可靠内核”
结论
权限最小化、沙箱隔离、幂等、断点续跑、预算熔断、高危操作人工审批、全链路留痕——这七件事不是可选项,是把概率系统放进生产的前提。
因果链
把 LLM 当成一个能力很强但不可靠的执行者,结论就非常直接:不能给它无限权限,不能让它在共享环境里裸奔,不能假设同一操作只执行一次,不能假设它知道什么时候该停,不能假设它出错会自己上报。人类组织解决同类问题靠的是制度装置:SOP、约束过程、权限划边界、审计留痕、演练覆盖罕见场景、绩效让失败有代价。Agent 目前这五样大多是零,只能用工程手段补上能补的部分。
反例
- 沙箱内允许直连外部 API,被构造的提示词触发高频调用,配额被刷爆。
- 没有幂等键,超时重试导致同一笔操作执行两次。
- 高危写操作(删除、转账、对外发消息)默认开放,只靠提示词劝阻。
- 没有 Trace,出事时无法回答“谁在什么权限下做了什么”。
检查项
- Agent 使用独立身份,权限按需开通,默认拒绝?
- 文件、代码、命令类操作在隔离环境执行?
- 所有写操作有幂等键?重试不会产生副作用?
- 单任务 token、调用次数、预算有上限且可熔断?
- 不可逆操作有“Agent 提议、人工确认”卡点?
- 全链路有 Trace,可按任务/工具/参数/结果检索?
来源
阿里手册第 14 章(安全)与 13 章(可观测性);OpenAI 的 guardrails 分层与 human intervention 触发条件;12-Factor 的“人类介入工具调用”。三家在“边界必须外置”上一致。
共识 6: 改进靠数据闭环,不靠感觉
结论
Trace -> 加工成数据集 -> 持续评估 -> 发现 Badcase -> 实验对比 -> 发布,这个闭环不建立,“优化”就退化为改提示词后观察两天。
因果链
Agent 的行为由模型、提示词、工具、上下文共同决定,任何一处变更都可能改变执行路径。没有可比对的回归集,就无法判断“这版比上版更好还是更差”;没有轨迹,就无法定位失败发生在理解、上下文、工具还是验证环节,于是团队只能在“感觉好多了”和“又出问题了”之间反复。
反例
- 回归报告只有通过率,没有轨迹,失败无法定位。
- 黄金集在发版时冻结,生产分布早已漂移。
- 每次变更都对着全部用例调参,最终过拟合测试集。
- Badcase 只修个案,不回流成用例,同类问题反复出现。
检查项
- 每次模型/提示词/工具/上下文变更,是否都有可比对的回归结果?
- 是否有 holdout 集不参与日常调参?
- Badcase 是否回流为固定用例?
- 评估对象是否包含轨迹(工具序列、参数),而不只是最终答案?
来源
阿里手册第 18-23 章的数据飞轮;Anthropic 关于评估与工具评估的工程文;12-Factor 关于“错误压缩进上下文”的实践。评估必须可回归、可追溯,是共同结论。
第二篇:精读 S 级(04-精读S级.md)
四份来源:Anthropic、12-Factor Agents、Manus、Cognition。
以下为转述与提炼,非逐字翻译;每条都给出「怎么做 / 不这么做会怎样」。个别细节「[未核实]」已在条目上标注。
一、Anthropic: 先把问题切开,再决定要不要 Agent
核心主张
绝大多数问题不需要 Agent,先判断用 workflow 还是 agent,再谈实现。
| 形态 | 谁决定路径 | 适用 |
|---|---|---|
| 单次调用 | 无路径 | 简单问答、抽取 |
| Workflow | 代码预定义 | 路径可枚举、需要稳定 |
| Agent | 模型运行时决定 | 路径不可枚举、需临场调整 |
可直接执行的结论
A1. 按“路径是否可枚举”选形态,不按“是否先进”选
- 怎么做:把主干路径画出来,能在一屏内枚举完 -> workflow;枚举不完且必须看中间结果 -> agent。
- 不这么做:把固定流程包装成 Agent,引入不确定性却不增加能力。
A2. 五种 workflow 模式覆盖大多数“看起来像 Agent”的需求
| 模式 | 做什么 | 典型场景 |
|---|---|---|
| 提示链 Prompt chaining | 拆成固定顺序的多步,每步校验 | 生成 -> 检查 -> 修订 |
| 路由 Routing | 先分类,再进不同分支 | 客服意图分流、模型分级 |
| 并行 Parallelization | 分段并行或多次投票 | 多维度审查、结果投票 |
| 编排者-工作者 Orchestrator-workers | 由模型拆任务、分派、汇总 | 子任务数量不定的复杂任务 |
| 评估者-优化者 Evaluator-optimizer | 一个生成、一个评审,循环改进 | 有明确评价标准的写作/代码 |
- 怎么做:先在这五种里找最接近的,找不到再考虑自主 agent。
- 不这么做:直接从零写 agent loop,重复实现已有的稳定模式。
A3. 工具接口 (ACI) 比提示词更影响成功率
- 怎么做:
- 工具描述按“给新同事写交接文档”的标准写,写清边界与反例;
- 参数名自解释,枚举值穷举,单位写进字段名;
- 错误信息要能指导下一步(“缺少 order_id,请先调用 search_order”),而不是抛堆栈;
- 一个工具只做一件事,返回结构化且可截断;
- 用 schema 与参数校验把“猜”的空间压到最小。
- 不这么做:提示词写得再好,模型仍会在参数格式、工具选择上反复出错。
A4. 停止条件必须显式,且不只一条
- 怎么做:同时设置最大轮次、token 预算、成功判据、人工检查点;任一触发即停。
- 不这么做:模型会在失败时继续重试,或在未完成时宣布完成。
A5. 保留“人在环”的显式出口
- 怎么做:把需要人确认的动作设计成一次工具调用,而不是让模型在文本里“请示”。
- 不这么做:审批变成口头声明,无法审计、无法阻塞执行。
A6. 把上下文当预算,而不是仓库
- 怎么做:
- 最小充分:只放当前一步决策需要的内容,历史按需检索,不预加载;
- 结构化优先:用字段、清单、状态块替代长段叙述;
- 分层压缩:近期原文,远期摘要,更早只留索引;
- 稳定前缀:系统提示与工具定义尽量不中途改动,保护缓存命中;
- 隔离子上下文:子任务用独立窗口,只回传结论,不回传全过程。
- 不这么做:上下文越长,指令权重越被稀释,模型越容易忽略关键约束,成本同时上升。
A7. 用“是否可枚举”判断 workflow 与 agent 的边界,而不是用“是否智能”
- 怎么做:把“必须看中间结果才能决定下一步”的环节标出来;标出的环节超过两处,才考虑 agent。
- 不这么做:把可枚举流程也交给模型决策,等于用不确定性替换确定性,收益为零。
适用边界
- 偏概念与模式,缺少大规模生产数据与成本曲线;
- 对“多 Agent”着墨少,不能据此判断多 Agent 是否适合你的场景;
- 上下文工程的量化阈值(多长该压缩)需按模型与任务自行标定。
来源:Anthropic《Building Effective Agents》(2024-12) 及其工具设计、上下文工程系列工程文。结论为转述 [未核实逐字表述]。
💡 深度核查与专家按语:官方原话是“寻找最简单的方案”,并未说五种模式“覆盖大多数”。准确的表述是:五种模式是决定上 Agent 前必须排除的选项。此外,Anthropic 对框架持尖锐的谨慎态度:指出框架(如 LangGraph)会遮蔽底层提示词与工具接线,默认不应在未理解底层之前使用框架。
二、12-Factor Agents: 把控制权拿回应用侧
核心主张
不要把控制流、上下文、状态交给框架隐式处理。框架可以帮你,但不能替你拥有这四样东西。
十二条与落地映射
| # | 原则 | 怎么做 | 不这么做会怎样 |
|---|---|---|---|
| 1 | 自然语言转工具调用 | 把用户意图稳定映射为结构化调用 | 意图靠正则硬编码,扩展即崩 |
| 2 | 自有提示词 | 提示词进版本库,可审查、可回滚 | 提示词藏在框架里,出问题无法定位 |
| 3 | 自有上下文窗口 | 自己决定放什么、放多少、怎么压缩 | 框架全量拼接,注意力被稀释 |
| 4 | 工具即结构化输出 | 工具调用本质是模型输出一个 schema | 把工具当黑盒 API,错误无法归因 |
| 5 | 统一执行状态与业务状态 | 执行到哪与业务到哪用同一份状态 | 两套状态分叉,重启后对不上 |
| 6 | 启动/暂停/恢复用简单 API | 状态可序列化,随时可读可续 | 长任务只能从头重跑 |
| 7 | 用工具调用来联系人类 | 审批、补充信息都是一次工具调用 | 人机交互游离在链路外,无法审计 |
| 8 | 自有控制流 | 循环、分支、终止由应用代码掌握 | 框架升级即行为变化,无法复现 |
| 9 | 把错误压缩进上下文 | 错误转成模型能继续的简短说明 | 原始堆栈塞满窗口,模型直接卡死 |
| 10 | 小而专注的 Agent | 一个 Agent 一个职责 | 万能 Agent 提示词膨胀,行为不可预测 |
| 11 | 从任何地方触发 | 入口与执行解耦 (CLI/IN/API) | 绑定单一入口,复用困难 |
| 12 | 无状态 reducer | {state, event} -> new state | 隐式全局状态,无法回放与测试 |
最关键的三条 (如果只做三条)
- #8 自有控制流:出问题时你能改的是代码,不是框架。
- #5 统一状态:任务状态与业务状态必须是一份,否则断点恢复必然出错。
- #12 无状态 reducer:能回放,才能复现;能复现,才能修。
适用边界
- 偏单机/CLI/长任务场景,企业后端需要把“入口”“审批”“多租户”再映射一层;
- 部分原则与“用托管平台省事”直接冲突,需要按团队能力取舍。
来源:12-Factor Agents (Dex Horthy / HumanLayer, 2025)。条目为中文转述 [未核实逐字表述]。
💡 深度核查与专家按语:十二条原则中,#8(Own your control flow)是其他十一条的根因前提。如果控制流不在你手里,#5 的统一状态无处落地,#12 的无状态 reducer 也无法实现。
三、Manus: 上下文工程的具体手法与代价
核心主张
上下文不是“能塞多少塞多少”,而是要在有限注意力预算下做取舍;KV-cache 命中率是首要工程指标。
六条可迁移手法
| 手法 | 具体做法 | 代价 / 边界 |
|---|---|---|
| 围绕 KV-cache 设计 | 保持前缀稳定,避免中途改动系统提示与工具定义 | 提示词迭代变慢,需要版本化 |
| 掩蔽而非移除工具 | 不用的工具用约束屏蔽,而不是从定义里删掉 | 需要可靠的掩蔽机制,否则误调用 |
| 用文件系统当上下文 | 大结果落文件,只把路径与摘要放进窗口 | 需要额外 IO 与权限管理 |
| 用“复述”操纵注意力 | 用 todo/计划文件反复写回目标,维持长任务不跑偏 | 增加 token 消耗,需控制频率 |
| 保留错误不清理 | 失败的动作与报错留在上下文,让模型避免重犯 | 窗口占用上升,需要压缩策略 |
| 避免 few-shot 固化 | 少给固定样例,防止模型机械模仿而失去泛化 | 对提示词质量要求更高 |
三条判断
- 上下文是预算,不是仓库:每多一段内容,都在稀释其他内容的权重。
- 稳定前缀 > 频繁优化:缓存命中带来的延迟与成本收益,通常大于一次提示词微调。
- 错误是后验:把失败从上下文里抹掉,等于让模型重复犯错。
适用边界
- 面向单产品形态 (通用 Agent 产品),企业内嵌场景需验证;
- 部分手法依赖自建运行时,托管平台未必开放。
来源:Manus《Context Engineering for AI Agents: Lessons from Building Manus》(2025)。为要点转述 [未核实逐字表述]。
💡 深度核查与专家按语:官方原话是:“如果只选一个指标,KV-cache 命中率是生产级 Agent 唯一最重要的单一指标”。因输入输出比约 100:1,缓存与未缓存成本差 10 倍。由此推导出硬性约束:前缀必须绝对稳定(不能放时间戳)、上下文必须 append-only、必须用 logit masking 屏蔽不可用工具而非直接删除。
四、Cognition: 为什么多数团队不该先上多 Agent
核心主张
多 Agent 的失败大多不是模型不够强,而是上下文被切碎后,隐含决策丢失。
两条论证
C1. 子任务之间必须共享足够上下文
- 怎么做:拆任务前先问“子任务 B 是否依赖子任务 A 过程中产生的隐含判断”;依赖则不要拆。
- 不这么做:两个子 Agent 各自做决定,最后合并时互相矛盾。
C2. 动作本身携带隐含决策
- 怎么做:把“写了什么、为什么这么写”当成状态的一部分传递,而不只传结果。
- 不这么做:下游只看到结果,看不到约束,复现时必然走偏。
结论与适用边界
- 单线程、线性推进的 Agent 在多数写操作场景更可靠;
- 只有当子任务真正独立、以只读为主、无需共享隐含决策时,多 Agent 才划算;
- 上下文窗口就是 Agent 的完整状态,压缩会丢信息,不能把压缩当成免费的扩容。
来源:Cognition《Don’t Build Multi-Agents》(2025)。为论证要点转述 [未核实逐字表述]。
💡 深度核查与专家按语(重要演进):2026 年 4 月 Cognition 更新了观点。多 Agent 在一种窄模式下被验证有效:写操作保持单线程,辅助 Agent(如搜索、评审)只贡献智能。验证者甚至不应与写者共享上下文以防污染。在此模式之外,原始警告依然成立。
五、四家之间的冲突点 (必须并列保留)
| 议题 | 一方观点 | 另一方观点 | 适用条件 |
|---|---|---|---|
| 要不要多 Agent | Cognition: 多数场景不要,上下文会碎 | Anthropic / OpenAI / 阿里: 编排者-工作者、manager、Multi-Agent 是有效模式 | 只读、子任务独立、可并行 -> 可多 Agent;有写操作、强顺序、共享隐含决策 -> 单 Agent |
| 先做简单还是先做完整 | Anthropic: 先用最简单方案 | 阿里: 按生命周期整体设计 | 立项期先简单验证;进入生产前补状态、治理、评估 |
| 控制流归谁 | 12-Factor: 应用自有 | 托管平台: 平台代管更省事 | 团队有工程能力且要可复现 -> 自有;追求上线速度且可接受锁定 -> 托管 |
| 上下文策略 | Manus: 稳定前缀、少 few-shot | 多数教程: 多给示例提升效果 | 长任务、成本敏感 -> 稳定前缀;短任务、格式要求高 -> 适示例 |
不做调和:这些冲突取决于场景,强行统一会得出错误结论。
六、S 级四家合起来的一句话
把 Agent 当成一个不可靠但可约束的执行者:先用最简单的形态,自己掌握控制流与状态,上下文按预算裁剪,完成由外部证据判定。
第三篇:精读 A 级(05-精读A级.md)
OpenAI 实践指南 + 阿里 AI Agent Handbook 选章。
阿里不逐章复述:只保留调研数据、运行地基、治理四维、实践失败复盘。
一、OpenAI 实践指南:把“边界”写成可执行配置
核心主张
Agent = model + tools + instructions,但能否上生产取决于 guardrails 与 human-in-the-loop 是否被显式设计。
1.1 什么时候值得构建 Agent
| 条件 | 说明 |
|---|---|
| 复杂决策 | 规则分支多到难以维护 |
| 难以维护的规则系统 | 维护成本已超过模型不确定性成本 |
| 非结构化输入 | 输入无法用固定 schema 约束 |
反向条件 (不适合): 路径固定、失败代价不可承受、无法验证结果。
1.2 三种编排方式
| 模式 | 结构 | 适用 | 风险 |
|---|---|---|---|
| 单 Agent | 一个模型 + 一组工具 | 大多数场景的起点 | 工具过多时选择困难 |
| Manager | 一个主 Agent 调用多个子 Agent 作为工具 | 子任务边界清晰 | 主 Agent 成为瓶颈与单点 |
| Decentralized | 多个 Agent 相互移交 | 高度自治、松耦合 | 责任链难追踪,冲突难裁决 |
落地映射:能从单 Agent 开始就不要上 Manager;上 Manager 必须给每个子 Agent 明确输入输出契约。
1.3 Guardrails 分层 (可直接按照做)
| 层 | 做什么 | 放在哪 |
|---|---|---|
| 相关性分类 | 拦截与业务无关的输入 | 入口 |
| 安全分类 | 识别越权、诱导、注入 | 入口 + 工具调用前 |
| PII 过滤 | 脱敏与阻断 | 输入与输出两侧 |
| 内容审核 | 输出合规 | 出口 |
| 工具风险分级 | 按读写/不可逆程度分级 | 工具注册表 |
| 规则型护栏 | 确定性硬规则 (白名单、额度) | 工具执行前 |
关键点:护栏是独立于模型的确定性组件,不能写成“请在提示词里注意安全”。
1.4 Human-in-the-loop 的触发条件 (必须写死)
| 触发 | 例子 |
|---|---|
| 超过失败阈值 | 同一任务重试 N 次仍失败 |
| 高风险动作 | 转账、删除、对外发送 |
| 不可逆动作 | 发布、支付、覆盖数据 |
| 低置信度 | 分类置信度低于阈值 |
落地映射:把“请求人工”实现为一次工具调用,而非模型在文本里请示。
1.5 护栏落地映射 (照这张表就能排期)
| 护栏 | 实现位置 | 触发后行为 | 失败处理 |
|---|---|---|---|
| 相关性分类 | 请求入口 | 拒答或转人工 | 记录原始输入,不调用模型 |
| 安全分类 | 入口 + 工具执行前 | 阻断并说明原因 | 计入安全事件,触发告警 |
| PII 过滤 | 输入与输出两侧 | 脱敏或阻断 | 记录字段类型,不记录原值 |
| 内容审核 | 响应出口 | 替换为合规话术 | 回退到人工审核队列 |
| 工具风险分级 | 工具注册表 | 高风险需审批 | 审批超时默认拒绝 |
| 规则型护栏 | 工具执行前 | 硬拦截 (白名单/额度) | 直接返回错误码,模型可读 |
判断护栏是否真的生效,只问一句:把模型换成最不听话的那个,护栏还拦得住吗? 拦不住,说明它只是提示词。
来源:OpenAI《A Practical Guide to Building Agents》(2025)。为结构化转述 [未核实逐字表述]。
二、阿里手册:只取三类不可替代的内容
2.1 先看数据:1906 份问卷的关键结论
(注:根据官方最新数据修正为 1906 份)
| 指标 | 数值 | 说明 |
|---|---|---|
| 已开发完成或开发中 | 46% | 去年 36% [未核实] |
| 真正部署到生产 | 18% | 唯一没有增长的指标 |
| 需要上下文与记忆管理 | 90% | 最普遍需求 |
| 最需补多模型路由与成本治理 | 63% | 成本是第二大痛点 |
| 仍靠人工抽查判断效果 | 55% | 评估方式原始 |
| 能拿运行轨迹自动评估 | 不足 8% | 能力缺口最大 |
| 单 Agent / 多 Agent / 人在回路 | 40% / 42% / 15% | 三种架构长期共存 |
| 上海:大型企业 vs 小微上线率 | 48% vs 16% | 开发率接近,上线率差 2-3 倍 |
| 深圳:大型企业 vs 小微上线率 | 38% vs 17% | 同上 |
| 多 Agent 头号难点:状态与上下文衰减 | 60% | 与 Cognition 的论证一致 |
怎么读这组数字:46% 与 18% 之间的 28 个点,不在模型选型里,而在状态、轨迹、验证三处。这与前四篇的结论完全吻合。
2.2 运行地基:第 7-9 章
| 章 | 一句话结论 | 可执行点 |
|---|---|---|
| 第 7 章 运行时与沙箱 | 工具调用要扩成可编程工作空间 | 隔离执行、资源限额、超时强杀 |
| 第 8 章 状态存储与语义资产 | 状态必须外置 | Event Log + Checkpoint;长期记忆与 RAG 分开承载 |
| 第 9 章 AI 网关与统一流量治理 | 流量要收口到一个治理点 | LLM / MCP / Agent 三类流量统一身份、配额、预算 |
最值得抄的一句:状态没外置,单人调试只是重来一次;生产并发下会变成任务丢失、重复执行、无法归因。
2.3 治理四维:第 13-16 章
| 维度 | 核心内容 | 落地要点 |
|---|---|---|
| 可观测性 (13) | Session / Trace / Span 三级模型 | 四类维度 (运行表现、稳定性、成本、审计);三层对象 (任务、执行、基础设施);四类采集 (埋点、插件、Hook、eBPF) |
| 安全 (14) | Prompt Injection 与高危授权 | 输入净化、身份隔离、工具权限、输出过滤 |
| 资产发现与管理 (15) | Prompt / Skill / Knowledge / Memory 台账 | 版本化、权限、复用 |
| 行为生成与质量验证 (16) | Agent Simulation: 用户模拟 + 环境模拟 | 边界是“不触达未授权生产、不产生不可控副作用”;三种模式结论不可混用 |
第 16 章三条硬结论:
- 仿真边界是授权与后果,不是实现方式;
- 全隐身模式下通过,不构成对真实依赖链的任何结论;
- 被测 Agent 本身不能进仿真,否则测的已不是它的决策。
2.4 实践篇:按失败模式重组 (第 25-29 章)
| 失败模式 | 案例线索 | 教训 |
|---|---|---|
| 以为“买个产品部署完就能跑” | 吉利汽车智能运维 | 日志、中间件、调用链断点未打通,Agent 无法生效 |
| 历史治理欠账 | 吉利:数据库账号混用 | 出事后期判断不出是哪个服务,必须先补治理 |
| 信任建立难 | 开发工程师仍想用老办法 | 从低风险测试环境切入,用省下的沟通成本换信任 |
| 告警风暴 | 并表后数百系统告警涌入 | 目标是一五三零:1 分钟发现、5 分钟定位、30 分钟恢复 |
| 从报警到自动修复的闭环 | PolarDB-X | 闭环的关键是验证与回滚,不是自动执行本身 |
其他案例 (ABAC1 内核补丁测试、Kitta 代码审查、塔斯汀门店运维、MiniMax 长周期记忆、哔哩哔哩内容洞察) 按同一结构提炼即可,不逐案展开。
2.5 阿里相对其他来源的三条唯一增量
- 完成判定:任务完成由环境证据判定,不由模型说停就停。
- 状态外置被提到架构级,而不是实现细节。
- 中国企业运维的真实失败复盘(账号混用、链路断点、信任阻力),这类内容其他来源没有。
2.6 明确建议跳过的部分
| 章节 | 原因 |
|---|---|
| 第 1-2 章 架构篇 | 概念与成熟度分级,选型时看一次即可 |
| 第 3-6 章 构建篇 | 与 Anthropic / 12-Factor 高度重复 |
| 第 10-12 章 异步、多 Agent、通信 | 按需查阅,不必通读 |
| 第 17-24 章 调优篇 | 只保留数据飞轮框架,细节可用 12-Factor 与评估实践替代 |
| 第 30 章 展望 | 叙事性内容,不影响决策 |
来源:阿里 AI Agent Handbook (2026, Apache 2.0);调研数字与篇章结构来自官方发布稿与在线阅读页,第 17、24、25-29 章精确标题 [未核实]。
第四篇:判读与落地清单(07-判读与落地清单.md)
这一页可以直接贴到评审材料或项目模板里。
用法:读白皮书前用「6 问」判断值不值得读;做项目时用三张检查单逐项打勾。
一、6 问判读法
| # | 问题 | 合格回答长什么样 | 不合格信号 |
|---|---|---|---|
| 1 | 什么场景不该用 Agent? | 给出明确边界与替代方案 | 只说“复杂场景适合 Agent” |
| 2 | 停止条件是什么? | 外部可验证的判据 + 多重上限 | “模型判断完成即可” |
| 3 | 状态存在哪里? | 外置、可序列化、可断点恢复 | 只提“记忆”,不提持久化 |
| 4 | 讲了哪些失败模式? | 有过程、有根因、有回滚 | 只有成功路径与架构图 |
| 5 | 评估是平均分还是门槛? | 每次变更可比对、可否决 | 只报通过率,没有基线 |
| 6 | 数字有样本量与口径吗? | 样本量、统计方式、对比基线 | “约 60%”“大部分团队” |
判定:6 问中答得上 4 个以上 -> 值得精读;2-3 个 -> 只读结论;≤1 个 -> 只作线索。
二、检查单 A:立项前
- 任务主干路径能否在一屏内枚举完?能枚举 -> 先考虑 workflow。
- 失败一次的业务代价是多少?是否可承受概率性失败?
- 是否存在“必须看工具返回才知道下一步”的环节?
- 完成判据能否不依赖模型自述?不能 -> 先设计判据再立项。
- 数据、权限、系统对接是否已就绪?未就绪 -> 先补治理,不要先上 Agent。
- 谁对最终结果负责?是否有明确的人工兜底角色?
三、检查单 B:上线前
运行
- 状态已外置,进程重启后可断点恢复?
- 工具调用有超时、重试上限、熔断?
- 沙箱隔离执行,网络出口受控?
安全 - Agent 使用独立身份,权限最小化,默认拒绝?
- 不可逆操作有“提议-确认”卡点?
- 输入侧有注入防护,输出侧有合规过滤?
可观测 - 全链路 Trace,可按任务 / 工具 / 参数 / 结果检索?
- 成本可按任务归因 (token、调用次数)?
- 失败可按阶段定位 (理解 / 上下文 / 工具 / 验证)?
评估 - 有黄金数据集,且含轨迹 (工具序列) 而不只是最终答案?
- 有 holdout 集,不参与日常调参?
- 每次变更都有可比对的回归结果?
四、检查单 C:持续运营
- 线上 Badcase 是否每周回流为固定用例?
- 是否有生产分布漂移的监控 (输入类型、工具成功率、平均步数)?
- 成本是否有单位任务基线?异常上涨能否告警?
- 模型 / 提示词 / 工具 / 上下文任一变更,是否走同一套回归门禁?
- 是否有版本回滚路径?回滚后状态是否兼容?
五、反模式与替代做法
| 反模式 | 为什么错 | 替代做法 |
|---|---|---|
| 用 Agent 做固定流程 | 引入不确定性却不增加能力 | 用 workflow 或一次结构化输出 |
| 停止条件写成“模型说完成” | 模型失败时也会说完成 | 外部判据 + 轮次/token 上限 |
| 把状态放在内存/会话里 | 重启即丢,并发下重复执行 | 外置存储 + 幂等键 |
| 用提示词做安全 | 提示词可被绕过 | 独立护栏组件 + 工具权限 |
| 只看最终答案 | 轨迹错误但答案碰巧正确 | 答案 + 轨迹 + 事实三层校验 |
| 全量历史塞进上下文 | 注意力稀释,成本上升 | 按任务编译上下文 + 压缩 |
| 一出问题就换模型 | 掩盖 Harness 缺口 | 先归因到上下文/状态/验证 |
| 多 Agent 解决复杂问题 | 上下文碎、隐含决策丢失 | 先单 Agent 线性推进,确需再拆 |
| 黄金集发版冻结 | 与生产分布脱节 | 定期从 Trace 补充并保留 holdout |
| 只修个案不回流 | 同类问题反复出现 | Badcase 入库并纳入回归 |
六、一页纸速查
该不该用 Agent:路径可枚举 -> workflow;否则 -> agent
骨架四件套:模型 + 工具 + 循环 + 停止条件
三个工程问题:上下文 / 状态 / 验证
瓶颈判断:先查 Harness,再换模型
可靠七件套:权限、沙箱、幂等、断点、预算、审批、留痕
改进闭环:Trace -> 数据集 -> 评估 -> Badcase -> 回归
如果一张检查单里有超过 3 项打不了勾,先别上线,先补缺口。
💎 结语:将 Agent 视作一个概率性推理引擎,用确定性的 Harness 将其包裹。先从最简单的形态起步,把控制流与状态攥在自己手里,通过外部证据而非模型自证来判定完成。
