作者：黑夜路人

时间：2026 年 7 月

开篇：别再把复杂 AI Agent 写成一条超长 Prompt

从“能跑一次”到“稳定交付”，真正需要的是一套闭环架构

过去两年，AI Agent 的能力边界被快速推高：模型可以理解目标、调用工具、生成内容、分析文件，甚至自行拆解任务。于是很多团队很自然地认为，只要把提示词写得更长、接入更多工具、增加更多模型调用，就能得到一个更强的 Agent。

但真实项目往往很快会撞上一堵墙：Demo 能跑，生产不稳；单步看起来都成功，最终结果却不合格；失败后只能从头再来；同一个输入多跑几次，路径和结果完全不同；一旦涉及成本、权限、合规或多人协作，系统就变得难以解释。

问题通常不在于模型“不够聪明”，而在于我们把一个复杂软件系统，误写成了一条超长 Prompt。

复杂 AI Agent 的本质，不是让模型获得无限自由，而是把模型的概率能力放进一个有状态、可验证、可恢复、有边界的软件闭环中。

本文给出一套可复用的方法：由调度器、规划器、执行器、评估器、修复器和交付器共同组成闭环，让 Agent 从“偶尔能完成”走向“能够解释为什么完成、如何失败、怎样修复、何时停止”。

一、什么时候需要把 Agent 当成复杂系统？

并不是每个任务都需要复杂架构。

如果任务只有一个明确输入、一个工具调用、一个可以直接验证的输出，那么一段 Prompt 加一个脚本往往已经足够。复杂化只会增加成本。

但当下面的情况同时出现两项以上，就应该警惕：你面对的已经不是“模型调用”，而是一个复杂 Agent 系统。

• 用户只给出模糊目标，系统必须先理解意图、补全约束；
• 任务包含多个互相依赖的阶段，前一步会影响后一步；
• 需要在多个工具、模型或外部服务之间选择；
• 中间步骤可能失败，而且不同失败需要不同恢复策略；
• “生成了文件”不等于“结果质量合格”；
• 需要控制费用、时间、并发、权限、隐私或内容风险；
• 任务执行时间较长，必须支持中断恢复；
• 结果需要被审计，必须说明输入、过程、证据和最终结论；
• 允许自动修复，但不能无限循环或反复消耗资源。

这类任务的共同特征是：开放语义与确定性约束同时存在。

用户表达的通常是“我想要什么”，系统却必须进一步回答：怎样才算完成？需要哪些步骤？哪些步骤可以并行？失败后重试还是换方案？结果如何验证？修复几次后必须停止？

如果这些问题没有被架构显式回答，它们最终都会被塞进同一条 Prompt，交给模型临场发挥。系统也就从“智能”变成了“不可控”。

二、先写不变量，再写功能清单

设计复杂 Agent 时，团队很容易先列功能：支持哪些模型、能调用多少工具、要不要多 Agent、是否接入向量库。

更稳妥的顺序恰恰相反：先定义不允许被破坏的系统不变量。

一套通用的不变量至少包括：

• 只有一个角色可以修改全局运行状态；
• 执行前必须形成版本化、可回读的计划；
• 每个阶段必须产生结构化结果，而不是只输出一段自然语言；
• 最终质量必须依据证据判断，不能依据“工具返回成功”；
• 硬门禁不能被平均分掩盖；
• 修复必须有范围、有预算、有最大轮次；
• 凭证、隐私数据和外部内容必须遵守最小权限；
• 所有终止都必须有明确原因；
• 最终交付必须与被评估的候选完全一致；
• 任何角色都不能通过删除证据、降低门槛或伪造成功来让流程通过。

这些不变量不是漂亮的架构口号，而是整个系统的“宪法”。模型、工具和工作流都可以替换，但不变量不能随意漂移。

三、把复杂 Agent 拆成四个平面

一个成熟的复杂 Agent，可以被理解为四个相互配合的平面。

1. 控制平面：谁决定下一步？

控制平面由调度器负责。它维护当前状态，决定下一步调用哪个角色，处理重试、回退、修复、终止和最终候选选择。

这里最重要的原则是：单一写入者。

规划器可以提出计划，评估器可以给出结论，修复器可以建议动作，但只有调度器能够改变全局状态。否则多个角色都能修改任务状态，就会出现重复执行、轮次错乱、并发覆盖和“各自认为已经成功”等问题。

2. 决策平面：把语义变成合同

决策平面包含规划、评估和修复决策。

规划器负责把模糊目标变成可执行合同；评估器负责依据证据判断是否达标；修复器负责把问题码映射成允许的修复动作。

这些角色都可以使用大模型，但输出必须是结构化的，并受到 Schema、规则版本和状态权限约束。

3. 执行平面：真正把事情做出来

执行平面负责调用模型、工具、数据库和外部服务，完成任务图中的每个节点。

它只执行计划，不擅自改变目标。每个阶段都必须返回统一结果，例如：是否成功、产物在哪里、使用了哪些输入、运行耗时、错误类型、重试建议、输出哈希和证据引用。

4. 治理平面：让系统可长期运行

治理平面往往最容易被 Demo 忽略，却决定系统能否进入生产。

它包括规则版本、数据合同、证据链、权限边界、成本预算、状态持久化、来源与许可、审计记录以及最终原子交付。

如果没有治理平面，Agent 即使“完成了任务”，团队也很难回答三个问题：它为什么这么做？结果是否值得信任？出现事故后能否复盘？

四、六个角色，分别解决六类问题

Scheduler：唯一的流程指挥者

调度器不负责创作内容，也不负责亲自执行工具。它的职责是维护一个清晰的状态机。

一个典型状态序列可能是：

Received → Planning → Executing → Evaluating → Repairing → Finalizing → Completed

同时还要允许 Blocked、Failed、Cancelled、BelowTarget 等终态。

调度器每次决策都应该能够解释：当前状态是什么、刚刚完成了什么、为什么选择下一步、预算还剩多少、是否达到终止条件。

“唯一调度权”看起来限制了 Agent 的自由，实际上它给并发和多 Agent 协作提供了安全边界。多个子任务可以并行执行，但它们只能提交结果，不能各自宣布全局成功。

Planner：把意图冻结成执行计划

规划器是复杂 Agent 中最容易被低估的角色。

弱规划只会生成一个步骤列表；强规划会生成一份可以被验证的执行合同，至少包含：

• 用户目标与不可违反的约束；
• 已知输入、缺失信息和合理假设；
• 成功标准与硬门禁；
• 任务依赖图以及可并行节点；
• 每个阶段的输入、输出和工具能力要求；
• 预算、超时、重试和降级策略；
• 证据采集方式；
• 可允许的修复动作；
• 规则版本与计划版本。

计划一旦进入执行阶段，就不应该被下游角色静默修改。确实需要改变目标时，应产生新版本，并由调度器重新确认。

这一步的意义是把“模型理解到了什么”外化，让后续执行和验收围绕同一份合同展开。

Generator / Executor：执行任务图，而不是自由发挥

执行器接收的是任务图中的一个工作项，而不是整段模糊需求。

一个合格的工作项通常包含：任务 ID、依赖、输入引用、期望输出、超时、最大重试次数、幂等键、允许使用的工具以及验收条件。

执行器需要遵守两个关键边界：

第一，外部返回的网页、文件、模型输出和工具日志都属于不可信输入，必须经过格式与安全校验。

第二，工具返回 success 只代表调用完成，不代表业务目标达成。执行器只报告事实，不能越权宣布最终成功。

Evaluator：先证明“发生了什么”，再评价“做得怎么样”

评估器不是一个简单的“请给结果打分”的 Prompt。

可靠评估应该分为两层。

第一层是确定性门禁：文件是否存在、结构是否合法、关键字段是否齐全、权限是否正确、运行结果是否可回读、输出与候选是否一致、是否触发安全或合规问题。

第二层才是语义质量：内容是否相关、信息是否完整、表达是否清晰、用户目标是否满足、结果是否具有可用性。

对于多维质量，可以使用统一公式：

最终分 = Σ（分项得分 × 归一化权重）÷ 分项数量

每项分数可以采用 0—10 分，但必须同时保留硬门禁。因为平均分有一个天然缺陷：一个严重错误，可能被其他维度的高分抵消。

例如，内容质量 9 分、表达质量 9 分，并不能抵消“泄露隐私”“没有真正写入目标系统”或“关键文件损坏”。这类问题必须直接阻断。

评估器的最佳输出不是一句“建议继续优化”，而是一份可执行报告：问题码、严重级别、证据位置、影响范围、建议动作、是否允许自动修复。

Repairer：修复产物，不修改考卷

修复器最重要的原则是：修问题，不修评估报告。

它不能降低阈值、删除失败项、忽略证据，也不能把真实失败改写成成功。它只能根据稳定问题码，从白名单中选择修复动作。

例如：重新生成某个局部结果、替换失效数据源、修正格式、重新执行受影响的下游节点、切换备用能力，或者请求人工补充关键输入。

修复不应默认全量重做。更合理的方法是利用任务依赖图，只让受影响节点及其下游失效，从而减少成本、时间和新回归。

Finalizer：交付的不是“最后一轮”，而是“最佳可信候选”

达到最大修复轮次，不代表最后一轮一定最好。

系统应该保存每轮候选、证据和评估结果，由调度器选择历史最佳的可交付候选。交付器再核对候选 ID、证据版本、文件哈希和目标目录，保证最终交付物正是被评估过的那一份。

这一步避免了一个隐蔽但常见的问题：评估器检查的是 A，最终交付的却是后来被覆盖的 B。

五、正确的闭环：每轮有证据，修复有上限

一个完整循环可以写成：

1. 1.接收目标和边界；
2. 2.规划器生成冻结计划；
3. 3.执行器按照任务图生成候选；
4. 4.系统从最终候选采集证据；
5. 5.评估器执行硬门禁和质量评分；
6. 6.达标则交付；
7. 7.未达标且仍有预算，则修复受影响子图；
8. 8.修复后重新生成候选并重新评估；
9. 9.达到最大轮次、预算耗尽、触发严重门禁或需要用户决策时，明确终止。

这里需要区分四种经常被混淆的“重试”：

• Provider 重试：一次网络或服务调用失败后的短重试；
• Stage 重试：某个任务节点重新执行；
• Repair Round：依据评估问题进行的一轮业务修复；
• New Run：目标或核心约束发生变化，开启一次新的完整运行。

如果把它们全部混成一个 retry_count，系统很快就会无法解释成本和状态。

还要防止“无效修复循环”：如果连续两轮问题码、证据和分数几乎不变，说明修复没有产生有效进展。此时应切换方案、请求人工介入或提前停止，而不是机械地继续消耗资源。

六、AI 负责判断，确定性工具负责证明

复杂 Agent 的可靠性，不来自把所有事情都交给模型，而来自正确划分概率能力与确定性能力。

适合交给 AI 的任务包括：

• 理解模糊意图；
• 从上下文中识别隐含约束；
• 对任务进行语义分类；
• 生成内容和候选方案；
• 判断相关性、风格与表达质量；
• 对复杂问题进行归因；
• 在多种方案中做权衡。

必须交给确定性工具的任务包括：

• 文件是否存在、能否打开、哈希是否一致；
• Schema 是否合法、字段是否齐全；
• 状态转换是否合法；
• 时间、尺寸、数量、费用和重试次数；
• 权限、许可、来源和审计记录；
• 公式计算、硬门禁与终止条件；
• 幂等写入和最终交付一致性。

一句简单的判断标准是：

如果一个结论可以通过程序精确计算或回读，就不要让模型凭感觉回答。

模型高分不等于事实正确，工具执行成功也不等于目标达成。两者必须在统一的证据合同中汇合。

七、Prompt 不应该是说明书，而应该是角色合同

复杂 Agent 当然需要 Prompt，但 Prompt 的作用不是容纳全部业务逻辑。

更可维护的做法是，把系统知识拆成三类：

共享规则

所有角色都必须遵守的不变量，例如安全边界、评分规则、数据处理原则、禁止事项、终止规则。

角色合同

每个角色只描述自己的目标、允许读取的输入、必须输出的结构、禁止承担的职责，以及失败时如何报告。

确定性 Schema

用机器可校验的数据结构定义计划、阶段结果、证据、评估报告、修复尝试和最终交付。

一个好的角色 Prompt 应当反复强调：

• 你当前是什么角色；
• 你只能做什么，不能做什么；
• 你的事实来源有哪些；
• 输出必须符合什么 Schema；
• 不确定时应该如何标记；
• 不能伪造工具结果；
• 不能修改全局状态；
• 不能通过放宽标准让任务通过。

规则还应该具备版本和内容哈希。规划器把所用规则版本冻结到计划中，下游角色发现规则漂移时拒绝继续。这样才能避免一个长任务执行到一半，验收标准悄悄发生变化。

六类数据合同，构成角色之间的共同语言

角色分工只有在数据合同清晰时才真正有效。至少应定义六类核心对象：

• Request：原始目标、输入材料、用户约束和授权范围；
• Plan：冻结后的目标、任务依赖、成功标准、预算和规则版本；
• StageResult：单个工作项的状态、产物、错误、耗时与证据引用；
• Candidate：可被整体评估的一份完整候选及其血缘；
• Evaluation：门禁结果、分项得分、问题码和证据位置；
• Delivery：最终选择的候选、文件清单、哈希和终止原因。

数据合同解决的不是“格式好看”，而是责任边界：规划器不能直接交付成品，执行器不能自行宣布通过，评估器不能覆盖候选，修复器不能重写历史证据。每个角色只向下游交付可校验对象，系统才能支持恢复、并发与审计。

八、多 Agent 不等于多个“自由意志”

复杂任务常常适合并行：多个信息源可以同时研究，多个独立素材可以同时处理，多组测试可以同时执行。

但多 Agent 的关键不是“多”，而是所有权。

安全的并发策略应该满足：

• 调度器拥有全局状态；
• 子 Agent 只拥有被分配的工作项；
• 每个工作项具有唯一 ID 和幂等键；
• 子 Agent 只能提交 StageResult，不能直接修改全局计划；
• 依赖未满足的节点不能提前启动；
• 并发上限、超时和预算由调度器统一控制；
• 汇总动作必须等到必要结果齐备后再执行。

换句话说，子 Agent 是并行执行者，不是平行指挥官。

九、怎样一步步开发，而不是一开始就造“大而全”？

复杂 Agent 最稳妥的开发顺序，不是先接入所有模型和工具，而是先完成最小闭环。

阶段一：定义问题与边界

• 明确用户目标、失败成本、硬门禁、权限边界、不可自动化的动作以及人工确认点。

阶段二：合同先行

• 先定义 Request、Plan、StageResult、Evidence、Evaluation、RepairAttempt 和 FinalDelivery 等核心数据结构。

阶段三：最小闭环

• 只支持一条最简单的 happy path，但必须完整走通规划、执行、评估和交付，不能用“文件存在”代替验收。

阶段四：加入有界修复

• 先支持少量高频问题码和白名单动作，验证依赖失效、重新评估、最大轮次和历史最佳候选选择。

阶段五：规则和 Prompt 工程化

• 把共享规则、角色合同、Schema、版本和哈希纳入正式运行链路。

阶段六：扩展外部能力

• 建立能力探测和适配层，区分“能力不可用”“凭证缺失”“临时失败”“输入不合格”和“任务本身不可完成”。

阶段七：真实场景回归

• 测试不应只覆盖 happy path。至少需要覆盖超时、部分成功、错误格式、无效修复、预算耗尽、并发冲突、恢复执行、权限不足和最终交付不一致。
• 只有闭环已经稳定，增加新工具和新模型才会真正提升能力，而不是扩大失败面。

十、交付前，用这十个问题检查你的 Agent

• 全局状态是否只有一个写入者？
• 执行前是否生成了版本化计划？
• 每个阶段是否有统一的结构化结果？
• 最终判断是否基于成品证据，而非中间成功状态？
• 是否存在不能被平均分抵消的硬门禁？
• 问题码能否映射到明确、有限的修复动作？
• 修复是否只重建受影响的依赖子图？
• 是否明确区分调用重试、阶段重试、修复轮次和新运行？
• 达标、阻断、预算耗尽和最大轮次是否都有明确终态？
• 最终交付物是否与被评估候选具有一致的 ID、版本和哈希？

如果其中有三项无法回答，这个系统很可能仍然只是一个高级 Demo。

结语：优秀 Agent 的标志不是更自由，而是更可信

复杂 AI Agent 的建设，最终不是 Prompt 技巧竞赛，也不是工具数量竞赛。

真正成熟的系统应该做到：

• 状态是唯一的；
• 决策是可解释的；
• 计划是可回读的；
• 执行是可恢复的；
• 结果是可验证的；
• 修复是有边界的；
• 成本是有限的；
• 权限和来源是可追踪的；
• 失败不会被包装成成功；
• 最终交付经得起再次检查。

当我们不再试图用一条超长 Prompt 解决全部问题，而是用调度、计划、证据、评估和有界修复构成闭环，AI 的不确定性才会从风险，转化为真正可用的生产力。