实用笔记：Harness工程——可靠AI智能体的基础
《实用笔记：工程化应用——可靠AI智能体的基础》操作指南：为采用该架构的团队提供的合同、校验机制以及可直接插入的代码模块。
本指南将逐步构建从原材料到可运行系统的完整流程，适用于《Harness Engineering：可靠AI智能体的基础》这一项目。重点在于可操作的步骤、明确的检查点，以及可直接放入代码仓库的代码，无需猜测其用途。
引言
在引言阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。相比庞大的脚本，更应采用小型且易于测试的单元。当某个步骤出现故障时，故障原因应能明确指向某个特定职责，而非整个复杂的流程。应在网关处进行身份验证，在数据层再次授权——仅凭承载令牌并不足以界定租户边界。
1. 首先：什么是LLM？
在进入第一阶段之前，需先明确输入内容、该步骤的负责人以及结束标准，然后再进行代码修改。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，设定成功检测标准，并拒绝默许部分完成的情况。 当下一步操作是编写代码或调用工具时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文字描述。
2. 什么是 AI 智能体？
对于第2点“什么是阶段”，在修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
3. 那么，什么是Harness？
在进入“3 So What”阶段之前，应先明确输入参数、该步骤的负责人以及结束标准，然后再修改代码。操作人员应当能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审核。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。
USER
|
v
+---------------+
| Agent Harness |
+---------------+
| | |
| | |
Context Tools Memory
| | |
+-----+-----+
|
v
LLM
|
v
Decision / Action
|
v
Tool / External System
|
v
Result
|
+------> Back to Agent
4. 为什么不能直接使用大语言模型？
在进入“4个为什么”阶段之前，需明确输入参数、该步骤的负责人以及终止标准，然后再进行代码修改。操作人员应能够从已知的检查点重新执行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 当下一步操作为代码编写或工具调用时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文字描述。 在进入“4个为什么”阶段之前，需明确输入参数、该步骤的负责人以及终止标准，然后再进行代码修改。操作人员应能够从已知的检查点重新执行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功判定标准，绝不允许出现无声无息的半完成状态。
User request
↓
LLM decides:
"I need to transfer money."
↓
Permission check
↓
Human confirmation
↓
Banking API
↓
Transaction result
↓
LLM explains result
5. 智能体循环
在完成“5个智能体循环”阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及代币或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试智能体循环将会耗费大量时间。
Observe
↓
Decide
↓
Act
↓
Observe result
↓
Decide again
↓
Stop
第一步 — 观察
在完成第一步“观察”阶段时，首先记下合约的详细内容：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。如果没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。
第二步 —— 做出决策
在完成“第2步：决策”阶段时，首先需写下接口契约：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续需要补充的内容。 需为每次调用记录工具名称、参数哈希值、响应延迟及最终结果。没有这些记录，调试过程将会浪费大量时间。 在完成“第2步：决策”阶段时，首先需写下接口契约：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 应将此阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝无声的半完成状态。
第3步 — 执行
将第三步的Act阶段视为可度量的界面使用效果最佳。在扩大范围之前，先记录一份优秀的测试用例、一个失败案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解这些成本信息，就能避免在从演示环境过渡到共享环境时出现意外费用。
第四步 —— 观察
将第4步的观察阶段视为可度量的界面使用效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 应将配置与应用程序代码分开。环境文件、密钥存储和功能标志应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。 提供具有严格数据结构定义及明确副作用标签的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。
第5步 —— 做出决策
将“第5步：决策”阶段视为可度量的对象来处理效果最佳。在扩大范围之前，需记录一份理想流程示例、一个失败案例以及回滚说明。同时将正常流程与恢复流程都记录下来。重试机制、人工审核环节以及错误处理方式都是产品本身的一部分，而非后续需要补充的内容。应提供具有明确结构规范和清晰副作用标识的工具，以便主机在自动批准之前能够知道哪些调用会改变系统状态。将“第5步：决策”阶段视为输入与经过验证的输出之间的契约，为相关文档命名、定义成功标准，并拒绝默许部分完成的情况。
第6步 — 停止
在第六步的停止阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解这些成本可以避免在从演示环境过渡到共享环境时出现意外费用。
6. 数学视角
在6 A Mathematical View阶段，应在修改代码之前明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。 在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。
7. Harness实际上控制什么？
在修改代码之前，针对“7 What Does the stage”阶段，需明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。 在修改代码之前，针对“7 What Does the stage”阶段，需明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入与经过验证的输出之间的契约。为相关输出文件命名，明确成功判定标准，杜绝无声的半完成状态。
背景信息
在处理上下文阶段时，首先写下契约内容：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。
User request
+
Previous conversation
+
Retrieved document
+
Tool result
+
System instructions
工具
在处理工具阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。如果没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。
内存
在完成“记忆”阶段的工作时，首先需写下接口契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续的优化工作。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。 在完成“记忆”阶段的工作时，首先需写下接口契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 应将此阶段视为输入与经过验证的输出之间的契约。为相关产物命名，明确成功判定标准，杜绝无声的半完成状态。
约束规范
将 Guardrails 阶段视为可度量的界面使用效果最佳。在扩大范围之前，先记录一份优秀的测试用例、一个失败案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外账单。
Can read customer information: YES
Can create support ticket: YES
Can delete customer account: NO
停止条件
将“停止条件”阶段视为可度量的界面来处理时，其效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 应将配置与应用程序代码分开。环境文件、密钥存储和功能标志应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 提供具有严格数据结构且带有明确副作用标签的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。
Maximum iterations = 5
8. 一个简单示例
将“8个简单示例”阶段视为可度量的对象来处理效果最佳。在扩大范围之前，需记录一份理想状态下的操作日志、一个故障案例以及回滚说明。同时将正常流程与恢复流程都记录下来。重试机制、人工审核环节以及错误处理都属于产品本身的功能，而非后续需要补充的内容。应提供具有明确结构规范和清晰副作用标识的工具，这样主机才能在自动批准之前知道哪些调用会改变状态。将“8个简单示例”阶段视为输入与经过验证的输出之间的契约，为相关文档命名、定义成功标准，并拒绝默许部分完成的情况。
User
↓
Agent
↓
Search Bristol population
↓
Result
↓
Search Bath population
↓
Result
↓
Calculator
↓
Comparison
↓
Final answer
9. Harness Engineering的用处何在？
在“9. Where is Harness”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在流程从演示环境转向共享环境时出现意外费用。
9. Where is Harness Engineering有何用处？
对于“9 Where is Harness”阶段，在修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。
客户支持
在客户支持阶段，应在修改代码之前明确输入内容、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新执行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的内容。