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隐式全局状态,无法回放与测试

最关键的三条 (如果只做三条)

  1. #8 自有控制流:出问题时你能改的是代码,不是框架。
  2. #5 统一状态:任务状态与业务状态必须是一份,否则断点恢复必然出错。
  3. #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(如搜索、评审)只贡献智能。验证者甚至不应与写者共享上下文以防污染。在此模式之外,原始警告依然成立。


五、四家之间的冲突点 (必须并列保留)

议题一方观点另一方观点适用条件
要不要多 AgentCognition: 多数场景不要,上下文会碎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 章三条硬结论:

  1. 仿真边界是授权与后果,不是实现方式;
  2. 全隐身模式下通过,不构成对真实依赖链的任何结论;
  3. 被测 Agent 本身不能进仿真,否则测的已不是它的决策。

2.4 实践篇:按失败模式重组 (第 25-29 章)

失败模式案例线索教训
以为“买个产品部署完就能跑”吉利汽车智能运维日志、中间件、调用链断点未打通,Agent 无法生效
历史治理欠账吉利:数据库账号混用出事后期判断不出是哪个服务,必须先补治理
信任建立难开发工程师仍想用老办法从低风险测试环境切入,用省下的沟通成本换信任
告警风暴并表后数百系统告警涌入目标是一五三零:1 分钟发现、5 分钟定位、30 分钟恢复
从报警到自动修复的闭环PolarDB-X闭环的关键是验证与回滚,不是自动执行本身

其他案例 (ABAC1 内核补丁测试、Kitta 代码审查、塔斯汀门店运维、MiniMax 长周期记忆、哔哩哔哩内容洞察) 按同一结构提炼即可,不逐案展开。

2.5 阿里相对其他来源的三条唯一增量

  1. 完成判定:任务完成由环境证据判定,不由模型说停就停。
  2. 状态外置被提到架构级,而不是实现细节。
  3. 中国企业运维的真实失败复盘(账号混用、链路断点、信任阻力),这类内容其他来源没有。

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 将其包裹。先从最简单的形态起步,把控制流与状态攥在自己手里,通过外部证据而非模型自证来判定完成。

Leave a Reply

Your email address will not be published. Required fields are marked *

lWoHvYe 无悔,专一