设计智能体工作流：实用示例

Source: Dev.to

上一篇文章聚焦于失败模式——代理出现错误的地方，以及我们在审查它们输出时出错的地方。此次跟进从诊断转向设计。

示例工作流

以下内容是一个示例工作流，专门结构化以应对那些失败模式。它并不是唯一的实现方式，也不打算作为永久方案。它是一种可行的设计，旨在将已知风险转化为明确的约束，并将验证重新引入循环中。

注意： 本文假设读者已熟悉之前的分析。如果您尚未阅读，本文所针对的失败模式已在此处概述：
Designing agentic workflows: where agents fail and where we fail.

目标受众

• 刚接触代理式编码的开发者 – 寻求谨慎、结构化的入门方案。
• 需要可审查提交的团队 – 工作流中内置了明确的验证关卡。
• 企业环境 – 需要可审计性、合规性以及低风险的生产部署。
• 希望避免常见 AI 失效模式的任何人 – 如过早的完成声明、静默删除测试以及浅层或硬编码实现。

不适用于

• 探索性黑客
• 绿地个人项目
• 审核性和问责性可选的环境

随着工具的改进和团队经验的提升，这些支撑结构大多可以被简化或移除。这是一种临时帮助，而非永久性规定。

核心约束

工作流围绕一个在第一篇帖子中隐含但尚未实现的单一约束构建：

验证必须独立于语言模型。

之前的失败模式聚焦于允许系统自行判断成功的结构性问题。置信分数、摘要和“完成”信号成为证据的替代品。此工作流明确将提案与验证分离。

阶段

其意图是 信任，但要验证。

改变优化目标

代理系统会针对它们能够观察到的内容进行优化：

• 绿色测试
• 合理的差异
• 明确的完成信号

在审查压力下，人类往往也会如此。为了改变这种优化目标，工作流程如下：

1. 将工作限制在小的、可审查的单元中。
2. 使意图明确且持久。
3. 在声称完成之前，强制提供独立的、机器可验证的证据。
4. 防止大量模糊的差异累积。

如果没有独立验证的约束，工作流程并不会实质性地改变这些结果。

循环结构

每个任务都以 written intent 开始，定义：

1. 正在更改的内容
2. 明确不更改的内容
3. 成功的标准
4. 用于验证的证据

这可以防止意图仅存在于对话历史中，并减少无声的范围漂移。

规划步骤

代理 不会 立即开始修改代码。它首先生成一个明确、可审查的计划。只有在该计划被接受后才开始执行，从而使架构和行为决策保持可见，降低意外差异的风险。

受限循环

每个循环的范围被限制在狭窄的范围内：

• 一个关注点
• 一次行为更改
• 一个验证目标

这使审查保持在人类认知负荷范围内，避免随着差异增大而从验证转向可信度的情况。

独立验证

完成需要由 语言模型之外的工具 产生的证据，例如：

• 测试执行结果
• 静态分析输出
• 类型检查器的通过或失败
• 实际运行时的追踪或日志

模型的解释和摘要仅提供上下文，而非验证。

清理阶段

每个循环以一次清理阶段结束，内容包括：

• 删除临时脚手架
• 删除死代码
• 合并重叠的辅助函数
• 更新注释以匹配行为

清理被视为正确性的一部分，而不是仅仅的外观改进；残留的代码会随着时间推高审查成本和认知负荷。

仓库和文档

该仓库包含同一工作流的多个变体，每个变体针对不同的工具进行了适配。从结构上看，这些工作流是 相同 的。

• 仓库: (在此添加链接或路径)

每个工作流记录的内容

• 循环的 阶段
• 代理 在每个阶段被允许执行的操作
• 人工 需要审查的内容
• 在进入下一个阶段之前必须存在的 制品

方法论文档

一个通用的方法论文档（docs/methodology.md）以 工具无关 的方式描述工作流的形状和约束。它使用命令式记号来说明各阶段，强调 循环的形状——而非具体语法——才是关键。

# 示例命令式记号（仅作说明）
phase 1: gather_requirements
phase 2: generate_solution
phase 3: review_by_human
phase 4: finalize_artifacts

将上述占位示例替换为方法论文件中实际使用的记号。

限制与未来工作

本文特意 未 逐步演示工作流；其机制已在代码库中记录。后续文章将详细演示一种变体，并展示此处描述的约束在实际中的执行方式。

该工作流并不试图修复模型；它改变模型运行的环境。小范围、持久意图以及独立验证能够降低以下方面的风险：

• 需求可能会悄然消失。
• 浅层实现可能会未被察觉地通过。
• 审阅者被迫进行可信性检查。
• 架构决策可能在未审查的情况下溜过去。

工作流假设如果结构允许，这些失败会发生。它的职责是让这些问题更难隐藏、检测成本更低。

采用指南

• 利用现有工作流： 如果您已经拥有完善的内部流程，可能只需要采纳本指南的部分内容。
• 尽早开始，避免陷阱： 如果您刚开始进行代理式编码，立即采用结构化方法可以帮助您在后期生产中规避昂贵的教训。

随着工具内置更好的防护措施，这些建议中的部分可能会变得多余。在此之前，深思熟虑的工作流设计仍是我们拥有的最可靠的控制手段。

结论

该仓库旨在被复制、适配，并最终超出其原有范围。这是一种实现方式——并非唯一方式。