首页 / 文章 / 《实用指南》：企业级AI智能体框架开发要点

software-architecture enterprise-architecture ai-agent generative-ai harness agents

《实用指南》：企业级AI智能体框架开发要点

《实用指南》操作流程详解：企业级AI智能体框架的运用——适用于采用该架构的团队的合同、校验规则及即用代码模块。

6175 词

以下说明旨在为“工程化企业级AI智能体框架”的应用提供实用路径。重点在于合同规范、校验机制以及可直接插入的代码占位符，而非激励性表述。在完成概览阶段时，首先明确合同规范：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续代码修改的透明度。将配置信息置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。

1. 模型、智能体与框架是不同的概念

将1模型智能体与流程视为可度量的对象时，其效果最佳。在扩大范围之前，先记录一个成功的用例、一个失败案例以及回滚说明。同时记录正常流程与恢复流程的细节。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的功能。需为每轮对话和每次会话设定token预算——智能体工具会大量消耗上下文，设置上限可避免演示过程变成意外的费用账单。

Observe → Reason → Validate → Act → Observe

2. 企业系统为何需要管控机制

将“2个为什么”企业系统方法视为可度量的分析层面时效果最佳。在扩大范围之前，先记录一份核心日志、一个故障案例以及回滚说明。优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤失败时，故障应指向单一责任主体，而非复杂的流程链。使用结构清晰、带有明确副作用标注的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。

3. 企业代理整合架构

在将企业代理阶段视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份优秀的处理案例、一个失败案例以及回滚说明。应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，绝不允许默许不完整的处理结果。需提供具有严格结构定义和明确副作用标注的工具。主机在自动批准之前必须清楚哪些调用会改变系统状态。

用户与应用程序边界

将用户与应用程序的边界视为一個可测量的界面，这样处理效果最佳。在扩大范围之前，先记录一份典型的成功案例、一个故障案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解这些成本信息，就能避免在从演示环境过渡到共享环境时出现意外费用。

规划器与状态管理器

将规划器与状态管理阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，先记录一份理想的运行日志、一个故障案例以及回滚说明。应将配置置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。提供具有严格数据结构定义且带有明确副作用标签的工具。主机需要在自动批准之前知道哪些调用会修改状态。

模型运行时

将模型运行阶段视为可度量的对象来处理，其效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程的文档。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。为每轮对话和每次会话设定token预算。智能工具会大量消耗上下文，设置上限可避免演示过程变成意外的费用账单。

工具注册表

将工具注册阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，先记录一份理想的运行示例、一个故障案例以及回滚说明。优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应指向单一的责任主体，而非复杂的流程链。使用结构简洁的工具，并明确标注其副作用。主机需要在自动批准之前知道哪些调用会改变状态。

策略引擎

将策略引擎阶段视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想运行案例、一个失败案例以及回滚说明。应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的半完成状态。需提供具有严格结构定义和明确副作用标识的工具。主机在自动批准之前必须清楚哪些调用会改变系统状态。将策略引擎阶段视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想运行案例、一个失败案例以及回滚说明。配置应置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。

约束规范

在“护栏”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程和异常恢复流程。重试机制、人工审批环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。

人工审批环节

在进入人工审批阶段之前，需明确输入内容、该步骤的负责人以及完成标准，然后再进行代码修改。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比庞大的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向具体的责任主体，而非复杂的流程链。在入口处进行身份验证，在数据层面再次授权——仅凭承载令牌并不足以界定租户边界。

工具执行器与沙箱

对于工具执行器和沙箱阶段，在修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。应将此阶段视为输入与已验证输出之间的契约。为相关产物命名，设定成功检测条件，并拒绝默许的半完成状态。在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。对于工具执行器和沙箱阶段，在修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个操作人员可审计的位置，无需查看整个系统结构。

内存与数据

在处理“内存与数据”阶段时，首先需明确相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改不会偏离原有设计。同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。若没有这些记录，调试过程将会耗费大量时间。

可观测性与追踪

在处理可观测性与追踪阶段时，首先需明确契约内容：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。建议使用小型、可测试的单元而非庞大的脚本。当某个步骤失败时，故障应能指向单一责任模块，而非复杂的流程链。需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试代理将陷入无休止的循环，耗费大量时间。

评估与反馈

在评估与反馈阶段工作时，首先写下契约内容：所需的输入参数、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合约定。将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝默许的半完成状态。需记录每次调用的工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。在评估与反馈阶段工作时，首先写下契约内容：所需的输入参数、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合约定。应将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于某个位置，以便操作人员无需查看整个系统结构即可进行审计。

4. 代理运行的逐步执行流程

将这一四步执行流程视为可度量的指标会更为有效。在扩大范围之前，先记录一份成功的处理案例、一个失败案例以及回滚说明。同时记录正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的功能。提供具有明确结构定义和清晰副作用标注的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。

第一步——接收并分类目标

将“第一步：接收与准备”视为一个可度量的流程最为有效。在扩大范围之前，先记录一份成功的案例、一个失败案例以及回滚说明。相较于庞大的脚本，应优先选择小型且可测试的单元。当某一步骤失败时，故障应能指向单一的责任主体，而非复杂的流程链。使用结构明确的工具，并为各种操作添加清晰的副作用标签。主机需要在自动批准之前知道哪些调用会改变系统状态。

第二步 — 构建受限上下文

将第二步的构建受限阶段视为可度量的对象来处理效果最佳。在扩大范围之前，需记录一份理想运行案例、一个失败案例以及回滚说明。应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的半完成状态。需提供具有严格结构定义和明确副作用标注的工具。主机方必须在自动批准之前了解哪些调用会改变系统状态。将第二步的构建受限阶段视为可度量的对象来处理效果最佳。在扩大范围之前，需记录一份理想运行案例、一个失败案例以及回滚说明。配置信息应置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。

第三步 —— 请求模型指示下一步操作

在第三步“提出问题”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。当下一步操作是编写代码或调用工具时，应优先使用具有架构验证的结构化输出，而非自由形式的文字描述。

第四步 — 在模型外部进行验证

在第四步的“外部验证”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型、可测试的单元。当某一步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。如果后续步骤是代码调用或工具调用，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文字描述。

第五步 —— 根据需要获取批准

在第五步“获取批准”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功判定条件，并拒绝默许的半完成状态。在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。在第五步“获取批准”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个操作人员可审计的位置，无需查看整个系统结构。

第6步——在受控环境中执行

在执行第6步时，首先需明确相关约定：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的一部分，而非后续需要补充的内容。需为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。没有这些记录，调试过程将会浪费大量时间。

第7步——规范观测数据

在执行“第7步：标准化处理”时，首先需列出相关约定：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。建议使用小型、可测试的单元，而非冗长的脚本。当某一步骤失败时，故障应能指向单一责任点，而非复杂的流程链。需为每次调用记录工具名称、参数哈希值、延迟时间以及处理结果。没有这些记录，调试过程将会浪费大量时间。

第8步 —— 继续还是停止

在处理第8步的“继续”阶段时，首先需写下契约内容：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合约定。将此阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝无声的半完成状态。需记录每次调用的工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。在处理第8步的“继续”阶段时，首先需写下契约内容：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合约定。应将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。

第9步 — 生成最终答案与追踪信息

将第9步“构建阶段”视为可度量的界面来处理效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。应提供具有明确结构规范和清晰副作用标识的工具，这样主机才能在自动批准之前知道哪些调用会改变状态。

5. 示例：应收账款处理工具

在将应收账款流程视为可度量的对象时，5个示例展示了其最佳运作方式。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。相较于复杂的脚本，应优先选择小型且可测试的单元。当某个步骤失败时，故障应能指向单一责任主体，而非错综复杂的流程。使用结构清晰、带有明确副作用标注的工具。主机需要在自动批准之前知道哪些调用会改变状态。

6. 驱动程序必须防止的故障模式

将该阶段视为可测量的表面时，最能有效应对6种故障模式。在扩大范围之前，先记录一份完美的测试用例、一个故障案例以及回滚说明。把这一阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，绝不允许默许部分完成的工作。使用具有严格结构定义和明确副作用标注的工具。主机需要在自动批准之前知道哪些调用会改变状态。

仅基于提示的安全机制

仅提示词的安全测试阶段，若将其视为可度量的评估维度，则效果最佳。在扩大测试范围之前，需记录一份理想的输出样本、一个失败案例以及回滚说明。在功能结果旁还需标注处理时间以及令牌或查询成本。提前了解成本情况，可避免在测试环境从演示模式转为共享环境时出现意外账单。应为每轮及每次会话设定令牌预算，因为智能代理工具会大量消耗上下文资源，设置上限能防止演示过程变成意外收费的源头。

模型与工具的直接连接

将“模型到工具的直接连接”阶段视为可测量的界面来处理，效果最佳。在扩大范围之前，先记录一份理想的运行案例、一个故障实例以及回滚说明。将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放，这样操作人员无需查看整个系统结构即可进行审计。为每轮对话和每次会话设定令牌预算。智能工具往往会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

功能过强的共享凭证

将“过度强大的共享凭证”阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，先记录一个成功的用例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。应提供具有严格结构定义且带有明确副作用标签的工具，这样主机才能在自动批准之前知道哪些调用会改变状态。

不可信内容变成指令

将“不可信内容转为指令”这一流程视为可度量的对象来处理时效果最佳。在扩大范围之前，先记录一份理想的执行日志、一个失败案例以及回滚说明。优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤失败时，故障应能指向单一责任主体，而非复杂的流程链。使用结构清晰、带有明确副作用标注的工具。主机需要在自动批准之前知道哪些调用会改变状态。

无限循环

将“无限循环阶段”视为可度量的界面来处理效果最佳。在扩大范围之前，需记录一份理想状态样本、一个故障案例以及回滚说明。应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的半完成状态。使用具有严格结构定义和明确副作用标注的工具。主机需要在自动批准之前知晓哪些调用会改变状态。将“无限循环阶段”视为可度量的界面来处理效果最佳。在扩大范围之前，需记录一份理想状态样本、一个故障案例以及回滚说明。配置应置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。

记录一切

在“完整日志记录”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续需要补充的功能。在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不能界定租户边界。

仅衡量流畅的回答

在仅检测流利回答的阶段，应在修改代码之前明确输入内容、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比庞大的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。在网关处进行身份验证，在数据层再次授权——仅凭承载令牌并不足以界定租户边界。

7. 设置本地 AI 开发环境

对于7，应在修改代码之前搭建阶段、明确输入参数、指定该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功检测标准，并拒绝默许的半完成状态。在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。对于7，应在修改代码之前搭建阶段、明确输入参数、指定该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个操作人员可以审核的位置，无需阅读整个系统结构。

前提条件

在完成前置条件阶段时，首先写下契约内容：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续需要补充的功能。需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。

mkdir enterprise-agent-harness
cd enterprise-agent-harness
python -m venv .venv

source .venv/bin/activate

.venv\Scripts\Activate.ps1

python -m pip install openai pydantic fastapi uvicorn python-dotenv

将配置与机密信息分开

在独立于阶段的 Keep 配置中工作时，首先需明确相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。建议使用小型、可测试的单元而非庞大的脚本。当某个步骤失败时，故障应能指向具体的责任模块，而非复杂的流程链。需为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。没有这些记录，调试代理将陷入无休止的循环，耗费大量时间。

AI_PROVIDER=openai
AI_MODEL=<approved-model-id>
OPENAI_API_KEY=<set-locally-never-commit>
HARNESS_ENV=development
HARNESS_MAX_STEPS=8
HARNESS_RUN_TIMEOUT_SECONDS=120
HARNESS_MAX_TOOL_RETRIES=2
HARNESS_REQUIRE_APPROVAL_FOR_WRITES=true

采用分层的项目结构

在处理“使用分层项目”阶段时，首先需明确合同条款：所需的输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明。将此阶段视为输入与验证后输出之间的契约。为相关成果命名，定义成功检测标准，并杜绝无声的半完成状态。需记录每次调用的工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试代理将陷入无休止的循环，浪费大量时间。

enterprise-agent-harness/
├── app/
│   ├── api.py                 # authenticated HTTP entry point
│   ├── harness.py             # observe/reason/validate/act loop
│   ├── model_adapter.py       # provider-specific model calls
│   ├── schemas.py             # typed proposals and observations
│   ├── tools/
│   │   ├── registry.py        # available capabilities
│   │   ├── invoices.py        # example read-only tool
│   │   └── email.py           # example external-write tool
│   ├── policy/
│   │   ├── engine.py          # allow/deny/require-approval
│   │   └── rules.yaml         # reviewed declarative policy
│   ├── approvals.py           # exact-action approval records
│   ├── sandbox.py             # isolated execution adapter
│   ├── state.py               # run and conversation state
│   ├── telemetry.py           # sanitized events and traces
│   └── redaction.py           # secret and sensitive-data filtering
├── evals/
│   ├── cases.jsonl            # representative tasks and attacks
│   └── run_evals.py
├── tests/
│   ├── test_policy.py
│   ├── test_tools.py
│   └── test_harness.py
├── Dockerfile
├── compose.yaml
├── .env
.example
└── pyproject.toml

在处理“使用分层项目”阶段时，首先需明确合同条款：所需的输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明。应将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。

首先明确自主性边界

将“定义自主性边界”这一阶段视为可测量的界面来处理效果最佳。在扩大范围之前，需记录一份理想的操作流程、一个故障案例以及回滚说明。同时将正常流程与恢复流程记录下来。重试机制、人工审核环节以及错误处理方式都是产品本身的一部分，而非后续需要补充的内容。应提供具有明确结构规范和清晰副作用标识的工具，以便主机在自动批准之前能够知晓哪些调用会改变系统状态。

8. 构建可运行的参考框架

将“8 Build a runnable stage”视为可度量的指标来使用效果最佳。在扩大范围之前，先记录一份理想的执行结果、一个失败案例以及回滚说明。优先选择小型且可测试的单元，而非冗长的脚本。当某一步骤失败时，故障应指向单一责任模块，而非复杂的流程链。使用结构明确的工具，并标注清晰的副作用信息。主机需要在自动批准之前知道哪些调用会修改状态。

定义类型化契约

将“定义类型化契约”阶段视为可度量的工作面，效果最佳。在扩大范围之前，需记录一份理想运行案例、一个失败案例以及回滚说明。应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的半完成状态。使用具有严格结构规范且带有明确副作用标签的工具。在自动批准之前，管理方必须清楚哪些调用会改变系统状态。

from enum import Enum
from typing import Any, Literal
from pydantic import BaseModel, Field

class Risk(str, Enum):
READ_ONLY = "read_only"
SENSITIVE_READ = "sensitive_read"
EXTERNAL_WRITE = "external_write"
DESTRUCTIVE = "destructive"
class ToolProposal(BaseModel):
tool: str
arguments: dict[str, Any]
reason: str
class PolicyDecision(BaseModel):
outcome: Literal["allow", "deny", "require_approval"]
reason_code: str
explanation: str
class Observation(BaseModel):
tool: str
ok: bool
data: dict[str, Any] = Field(default_factory=dict)
error_code: str | None = None
class RunState(BaseModel):
run_id: str
user_id: str
tenant_id: str
goal: str
step: int = 0
observations: list[Observation] = Field(default_factory=list)
finished: bool = False

将“定义类型化契约”阶段视为可度量的工作面，效果最佳。在扩大范围之前，需记录一份理想运行案例、一个失败案例以及回滚说明。配置信息应置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。

为工具注册安全元数据

对于具有安全级别的 Register 工具，在修改代码之前需明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误消息处理都是产品本身的组成部分，而非后续需要补充的功能。在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不能作为租户边界。

from dataclasses import dataclass
from typing import Callable

@dataclass(frozen=True)
class ToolDefinition:
name: str
risk: Risk
handler: Callable[..., dict]
timeout_seconds: int
idempotent: bool
TOOLS = {
"list_overdue_invoices": ToolDefinition(
name="list_overdue_invoices",
risk=Risk.SENSITIVE_READ,
handler=list_overdue_invoices,
timeout_seconds=10,
idempotent=True,
),
"send_email": ToolDefinition(
name="send_email",
risk=Risk.EXTERNAL_WRITE,
handler=send_email,
timeout_seconds=15,
idempotent=False,
),
}

实现确定性策略

在实施确定性策略阶段，应在修改代码之前明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。应在网关处进行身份验证，在数据层面重新授权——仅凭承载令牌并不足以界定租户边界。

def authorize(state: RunState, proposal: ToolProposal) -> PolicyDecision:
definition = TOOLS.get(proposal.tool)
if definition is None:
return PolicyDecision(
outcome="deny",
reason_code="UNKNOWN_TOOL",
explanation="The requested capability is not registered.",
)

if not identity_can_use_tool(
user_id=state.user_id,
tenant_id=state.tenant_id,
tool=definition.name,
arguments=proposal.arguments,
):
return PolicyDecision(
outcome="deny",
reason_code="NOT_AUTHORIZED",
explanation="The caller lacks permission for this resource.",
)if definition.risk in {Risk.EXTERNAL_WRITE, Risk.DESTRUCTIVE}:
return PolicyDecision(
outcome="require_approval",
reason_code="CONSEQUENTIAL_ACTION",
explanation="The exact action must be approved before execution.",
)return PolicyDecision(
outcome="allow",
reason_code="POLICY_ALLOWED",
explanation="The action is permitted within the caller's scope.",
)

将审批与具体操作绑定

为使绑定操作能够进入该阶段，需在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功检测标准，并拒绝默许的半完成状态。在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。为使绑定操作能够进入该阶段，需在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个操作人员可审计的位置，无需查看整个系统结构。

import hashlib
import json

def action_digest(state: RunState, proposal: ToolProposal) -> str:
value = {
"user_id": state.user_id,
"tenant_id": state.tenant_id,
"tool": proposal.tool,
"arguments": proposal.arguments,
}
canonical = json.dumps(value, sort_keys=True, separators=(",", ":"))
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

实现受控循环

在处理“实现受控循环”这一阶段时，首先需明确相关规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改不会偏离原有设计。同时记录正常执行路径和异常恢复路径。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续需要补充的内容。需为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。没有这些记录，调试循环结构将会耗费大量时间。

async def run_harness(state: RunState, model, approvals, executor):
max_steps = 8

while not state.finished and state.step < max_steps:
state.step += 1context = build_bounded_context(state, TOOLS)
response = await model.next_action(context)if response.final_answer is not None:
state.finished = True
return complete_run(state, response.final_answer)proposal = ToolProposal.model_validate(response.tool_proposal)
decision = authorize(state, proposal)
trace_policy_decision(state, proposal, decision)if decision.outcome == "deny":
state.observations.append(Observation(
tool=proposal.tool,
ok=False,
error_code=decision.reason_code,
))
continueif decision.outcome == "require_approval":
digest = action_digest(state, proposal)
if not approvals.has_valid_approval(digest):
return pause_for_approval(state, proposal, digest)observation = await executor.execute(
definition=TOOLS[proposal.tool],
arguments=proposal.arguments,
identity={
"user_id": state.user_id,
"tenant_id": state.tenant_id,
},
)
state.observations.append(redact_observation(observation))return stop_run(state, reason="STEP_LIMIT_REACHED")

通过适配器连接模型

在完成“通过阶段连接模型”这一工作时，首先需明确相关约定：所需的输入参数、成功信号，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。相较于冗长的脚本，应优先使用小型且可测试的单元。当某个步骤出现故障时，故障原因应能指向具体的责任模块，而非复杂的流程链。对稳定的系统指令和工具结构进行缓存。重复发送相同的开头信息是导致资源浪费的常见原因。

class ModelAdapter:
async def next_action(self, context) -> "ModelTurn":
raise NotImplementedError

提供经过身份验证的 API

在“暴露已认证的 API”阶段工作时，首先需写下接口契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合约定。将此阶段视为输入与经过验证的输出之间的契约。为相关文件命名，明确成功判定标准，并杜绝无声的半完成状态。需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。

from fastapi import Depends, FastAPI

app = FastAPI()
@app.post("/runs")
async def create_run(request: RunRequest, identity=Depends(require_identity)):
state = RunState(
run_id=new_run_id(),
user_id=identity.user_id,
tenant_id=identity.tenant_id,
goal=request.goal,
)
return await run_harness(state, model, approvals, executor)
@app.post("/runs/{run_id}/approvals")
async def approve_run_action(
run_id: str,
request: ApprovalRequest,
identity=Depends(require_identity),
):
return approve_exact_action(run_id, request.action_digest, identity)

在处理“暴露已认证的 API”阶段时，首先需明确接口契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合规范。应将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放，以便运维人员无需查看全部代码即可进行审计。

在本地运行

将“在本地运行”阶段视为可度量的测试场景效果最佳。在扩大测试范围之前，需记录一份理想的运行日志、一个失败案例以及回滚说明。同时文档化正常流程与故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品功能的一部分，而非后续需要补充的内容。应提供具有明确结构定义和清晰副作用标识的工具。主机需要在自动批准之前知道哪些调用会修改状态。

uvicorn app.api:app --host 127.0.0.1 --port 8000 --reload

9. 测试与评估该集成方案

在“测试与评估”阶段，将其视为可度量的对象会更为有效。在扩大范围之前，需记录一个成功的测试案例、一个失败案例以及回滚说明。相比复杂的脚本，应优先选择小型且易于测试的单元。当某个步骤失败时，故障应能指向具体的责任模块，而非复杂的流程链。应使用结构清晰、带有明确副作用标注的工具，这样主机在自动批准之前就能知道哪些调用会改变系统状态。

确定性单元测试与集成测试

将确定性单元测试与集成阶段视为可度量的对象，效果最佳。在扩大范围之前，需记录一份理想测试用例、一个故障案例以及回滚说明。应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，绝不允许默许部分完成的工作。应使用具有严格结构且带有明确副作用标注的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。将确定性单元测试与集成阶段视为可度量的对象，效果最佳。在扩大范围之前，需记录一份理想测试用例、一个故障案例以及回滚说明。配置应置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。

def test_external_write_requires_approval():
proposal = ToolProposal(
tool="send_email",
arguments={"to": "customer@example.test", "body": "Reminder"},
reason="Send the approved reminder",
)

decision = authorize(make_finance_run(), proposal)assert decision.outcome == "require_approval"
assert decision.reason_code == "CONSEQUENTIAL_ACTION"

模型与工作流评估

在进行模型与工作流评估阶段时，应在修改代码之前明确输入参数、各步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。当下一步操作为代码编写或工具调用时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文字描述。

10. 在企业规模上部署该框架

在“10 部署 harness”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向某个特定职责，而非整个复杂的流程。应在网关处进行身份验证，在数据层再次授权——仅凭承载令牌并不足以界定租户边界。

生产环境拓扑结构

在生产拓扑阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功检测标准，并拒绝默许的半完成状态。在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。

Client
│
▼
API Gateway / WAF
│  authentication, rate limits, request ID
▼
Harness API
├── Policy Service
├── Approval Service
├── Model Gateway ─────► Model Provider
├── State Store
├── Trace / Audit Pipeline
└── Tool Executor Queue
│
▼
Isolated Workers
├── MCP / SaaS APIs
├── Browser Sandbox
├── Code Sandbox
└── Enterprise Data

在生产拓扑阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作人员无需查看整个架构即可进行审计。

将控制平面容器化

在处理“将控制平面容器化”这一阶段时，首先需明确相关规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。同时记录正常流程与故障恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。

FROM python:3.12-slim

WORKDIR /app
COPY pyproject.toml ./
RUN pip install --no-cache-dir .COPY app ./appRUN useradd --create-home --uid 10001 harness
USER harnessENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1CMD ["uvicorn", "app.api:app", "--host", "0.0.0.0", "--port", "8000"]

生产环境控制

在处理生产环境控制阶段时，首先写下合同规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。建议使用小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应能指向单一的责任模块，而非复杂的流程链。需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。

从开发到生产的路径

在从开发环境到生产环境的过渡阶段，首先需明确相关约定：所需的输入参数、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合约定。将这一阶段视为输入与已验证输出之间的契约。为相关产物命名，定义成功检测标准，杜绝默许的部分完成情况。需记录每次调用的工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。在从开发环境到生产环境的过渡阶段，首先需明确相关约定：所需的输入参数、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合约定。应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，以便操作人员无需查看整个系统结构即可进行审计。

11. 企业就绪性检查清单

将11个企业就绪性检查清单阶段视为可度量的指标来使用效果最佳。在扩大范围之前，需记录一份理想流程示例、一个故障案例以及回滚说明。

同时记录正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续需要补充的功能。

应提供具有明确结构定义和清晰副作用标注的工具。在自动批准之前，系统管理员需要知道哪些调用会改变系统状态。

结论

将结论阶段视为可度量的指标来使用效果最佳。在扩大范围之前，需记录一份理想流程示例、一个故障案例以及回滚说明。

参考资料

操作检查清单

全部文章发送简报