Agent Spec：如何用自然语言定义一个可执行系统

如果你会写简单的循环和条件判断，也写过提示词（Prompt），可以把 Agent Spec 理解为一份任务规范：它告诉 Agent 要完成什么、按什么步骤做、遇到什么情况重试，以及何时停止。

本文以整理文档为例，说明怎样把这些要求写进自然语言指令。这里的“可执行系统”指模型与运行程序按规范共同完成任务；规范本身不会自动执行工具、保存状态或强制停止循环。

先给结论 #

1. Agent Spec 用自然语言约定任务如何执行。 它写清当前做到哪一步、下一步由什么条件决定，作用类似状态机中的状态与转移规则。状态机就是把“当前阶段”和“允许进入的下一阶段”明确列出来。
2. 本文用 6 个方面检查规范是否完整： 目标（Goal）、工作流（Workflow）、迭代机制（Iteration）、约束规则（Rules）、拆解能力（Decomposition）与输出规范（Output Contract）。简单任务可以不需要循环或拆分，但应明确这一点。
3. 循环需要终止条件。 只要求“继续改进”，却不说明何时停，Agent 就可能重复修改或推翻已有结果。轮数上限能限制执行次数，不能保证每轮判断都正确。
4. 设计时可以沿用程序化思维： 拆出步骤，写明判断和循环条件，限制允许的操作，再规定输出结构。

Agent Spec 的 6 大核心组件 #

下面按六个方面检查一份 Agent Spec。每一项都应让执行者知道自己要做什么，也让调用方知道如何验收：

1. Goal（目标） #

定义任务"最终要达成什么"。 好的目标必须是可验证的，并且有明确的终态（done condition）。

常见的错误写法（太模糊）：

帮我优化一下这些文档

工程化的写法：

将输入的散乱文档集合，重构为结构清晰、命名规范统一的工程文档体系，包含功能说明、API 接口和部署指南三部分。

2. Workflow（工作流） #

工作流定义任务“怎么做”：把处理过程排成有先后关系的步骤，前一步的结果供后一步使用。这样的连续处理也叫 pipeline（流水线）。

一个清晰的 workflow 可能长这样： 遍历 → 分析 → 修改 → 迭代 → 输出

每一步都要说明处理什么、做什么、产生什么结果。例如“分析”应交代分析哪些文档、找哪些问题，否则模型仍要猜测你的要求。

3. Loop / Iteration（迭代机制） #

这里要回答：系统是否需要根据上一步的结果，再做一次审查或修改？如果需要，就要把重复执行的规则写出来。

你必须在 Spec 中定义：

• 是否需要循环？
• 循环的条件是什么？
• 终止条件（收敛机制）是什么？

例如：

重复审查和优化文档内容，直到无法提出实质性改进或经过 3 轮优化为止。

这条指令同时给出内容标准和次数上限：没有实质改进时提前结束，否则最多做三轮。运行程序还需记录轮数并执行停止规则，不能只依赖模型自行记住上限。

4. Rules / Constraints（约束规则） #

约束规则说明允许怎样处理任务，以及哪些操作不能做。主要包括：

• 风格约束：使用工程化语言，保持简洁。
• 行为约束：如果判断条件满足，直接执行无需反复确认。
• 安全约束：不允许覆盖未备份的原始数据。

5. Decomposition（拆解能力） #

输入较多或任务包含不同类型的工作时，可以拆成较小单元逐个处理。拆分后仍需说明各部分如何合并，否则局部修改可能互相冲突。规范需要交代：

• 如何拆任务
• 如何拆文档
• 如何拆模块

6. Output Contract（输出规范） #

如果后续程序要读取结果，就需要约定输出格式，例如 JSON 字段或 Markdown 结构。这就是 Output Contract：输出方和接收方共同遵守的格式要求。模型若返回一段自由文本，接收方可能找不到所需字段，因而无法继续处理。

假设任务是整理前面提到的文档，规范可以要求按功能说明、API 接口和部署指南分组；每组先检查命名，再修改内容，最后按约定目录输出。若某轮仍发现问题，但已达到三轮上限，就停止并报告未解决项。这样，目标、步骤、循环和输出便对应到同一个任务。

编排工作流的 4 步设计法 #

在编写 Agent Spec 时，可以遵循这个实用的"4步法"：

Step 1：把任务"程序化" #

在写每一段描述时，先问自己：如果这是代码，我会怎么写？

当你脑海中有了类似这样的伪代码：

for file in folder:
    optimize(file)
    while can_improve:
        refine(file)

再把这段逻辑翻译成严谨的自然语言指令。

Step 2：加入"智能体能力" #

在流程中写明哪些情况需要判断，以及判断后分别执行什么：

• 增加判断条件（if）
• 控制循环流（while）
• 细化任务拆分（split）
• 引入思考空间（decide）

Step 3：加入约束（防止失控） #

补齐各种边界情况的防御：

• “当遇到未知术语时，不要自行编造，应保持原文标注。”
• “命名必须遵守驼峰规范。”
• “输出过程中不要产生解释性废话。”

Step 4：定义终止条件 #

补齐终止条件：达到验收标准时结束；仍未达到标准但已用完轮数或预算时，也要停止，并说明剩余问题。这里的“收敛”就是让重复执行最终停在一个可检查的结果上。

Agent Spec 通用模板 #

下面的模板汇总了前面六项要求。按任务填写，删去确实不需要的部分：

# Goal
<定义最终目标，必须有明确终态>

# Workflow
1. <可执行步骤 1>
2. <可执行步骤 2>
...

# Iteration
- 循环执行 <某步骤>
- 直到满足：
  <明确的终止条件>

# Decomposition
- 当满足以下条件时拆分：
  <拆分规则>
- 对拆分后的单元重复执行本流程

# Rules
- <约束准则 1>
- <约束准则 2>

# Naming / Structure (optional)
- <命名规范要求>
- <目录/输出结构规范>

# Output Contract
最终输出必须满足：
- <条件 1>
- <条件 2>
- <格式定义，如 JSON Schema>

设计质量的 5 个评判标准 #

写完一个 Agent Spec 后，试着用这 5 个维度来评判它是否优秀：

1. 可执行性（Executable）：指令是不是悬在空中的？能不能直接按步骤跑下来（甚至是由人脑对照模拟执行）？
2. 收敛性（Convergence）：循环是否有可检查的停止条件和次数上限？停止时能否说明哪些要求已经满足、哪些仍未满足？
3. 可控性（Controllability）：它会不会乱改不该改的数据？有没有输出无法解析的内容？
4. 可扩展性（Scalability）：如果以后要加新规则，能不能在当前的流程结构中平滑插入？
5. 可组合性（Composable）：其他任务能否按约定提供输入并使用结果？如果要把它交给多 Agent 系统中的一个执行者，就需要清楚的输入要求和输出格式。

绝不能犯的错误 #

下面这些缺口会让执行过程难以控制：

• ❌ 没有终止条件：AI 可能会陷入自我推翻的死循环，一直改下去。
• ❌ 目标太模糊：执行者不知道什么结果算完成，调用方也难以验收。
• ❌ 全开放无约束：模型可能处理不该修改的内容，或返回后续程序无法使用的结果。
• ❌ 将一次性任务包装为 Agent：如果一次提示就能完成任务，也不需要保存进度或根据结果决定下一步，就没有必要增加循环和调度逻辑。
• ❌ 缺乏输出结构设计：导致下游系统无法对接使用。

进阶：你可以做得更远 #

把目标、判断、循环和验收写清楚后，你就在设计 Agent 的工作流程了。下面是本文用来区分工作内容的示意分层，并非通用能力评级：

下一步，可以把这份 Spec 转成 Python Agent 脚本，例如用 LangChain 或自行编写的运行循环来执行。先让程序实际记录进度、检查输出并限制轮数，再考虑把子任务交给多个 Agent。若要加入自动评分，也需要先说明评分依据：它检查的是格式、事实还是任务完成情况，以及评分结果会触发重试还是停止。

上一篇：Human-in-the-Loop：Agent 什么时候应该停下来问你