AI智能体最佳实践——可投入生产的工程化方案

可将此内容视为《AI智能体最佳实践：可用于生产的工程化方法（2026指南）》中理念的面向操作人员的简化版本：清晰的阶段划分、有序的代码模块以及能在交接过程中保留的恢复说明。 将“概览”阶段视为可量化的基准最为有效。在扩大范围之前，先记录一份最佳操作案例、一个故障实例以及回滚说明。 在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外账单。

什么是智能体工程化框架？为何需要它？

在“什么是代理”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不能作为租户边界。

不可妥协的原则（来自代码库）

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

深入探讨 agents-best-practices 代码库

在深入研究某个阶段时，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 相较于庞大的脚本，应优先选择小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向某个具体的责任模块，而非整个复杂的流程。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。 在深入研究某个阶段时，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 除了功能结果外，还应记录执行时间以及令牌或查询的成本。提前了解成本情况，可避免在流程从演示环境转向共享环境时出现意外账单。

参考文件一览

在处理某个阶段的参考文件时，首先记下相关契约：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放于一处，这样操作人员无需查看整个系统结构即可进行审计。 为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。如果没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。

为何这不是“又一则建议清单”

在分析“为何这不是阶段化处理”时，首先需列出相关约定：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续需要补充的功能。 需为每次调用记录工具名称、参数哈希值、延迟时间以及处理结果。没有这些记录，调试代理时将会浪费大量时间。

适用于生产环境的代理程序核心原则（摘自相关技能文档）

在处理“面向生产环境的关键原则”这一阶段时，首先需明确合同条款：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明可追溯。 相比冗长的脚本，应优先选择小型且易于测试的单元。当某个步骤出现故障时，故障点应指向单一责任模块，而非复杂的流程链。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。 在处理“面向生产环境的关键原则”这一阶段时，首先需明确合同条款：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明可追溯。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。

1. 模型提出方案——执行层负责落实

“1模型”认为，将执行阶段视为可度量的对象最为有效。在扩大范围之前，先记录一份最佳案例、一个失败实例以及回滚说明。 配置应与应用程序代码分开存放。环境文件、密钥存储和功能开关应集中管理，这样操作人员无需查看整个系统结构即可进行审计。 为每轮对话和每次会话设定令牌预算。智能工具往往会大量消耗上下文资源，设置上限可避免演示过程突然产生额外费用。

2. 每次工具调用都会返回结果——即使失败也是如此

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

3. 风险会改变流程

将“3个风险”对应的阶段视为可度量的对象来处理时，其效果最佳。在扩大范围之前，需记录一份理想的操作日志、一个故障案例以及回滚说明。 相比庞大的脚本，应优先选择小型且可测试的单元。当某一步骤出现故障时，故障应指向单一责任主体，而非复杂的流程链。 应使用具有明确结构规范和清晰副作用标注的工具。在自动批准之前，主机需要知道哪些调用会修改状态。 将“3个风险”对应的阶段视为可度量的对象来处理时，其效果最佳。在扩大范围之前，需记录一份理想的操作日志、一个故障案例以及回滚说明。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。

4. 上下文是逐步构建的，而非一次性输入的

在“4 Context已组装”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。

5. 长时间运行的任务应有预算限制

对于那些包含多个阶段的长期任务，在修改代码之前需明确输入参数、各步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏状态。需同时记录正常流程与故障恢复流程。重试机制、人工审核环节以及错误消息处理都是产品本身的组成部分，而非后续需要补充的功能。应在网关处进行身份验证，在数据层再次授权——仅凭承载令牌并不能界定租户边界。

6. 反复出现的故障会演变为产品功能

对于那些会反复出现的6种故障场景，在修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 相较于庞大的脚本，应优先使用小型且可测试的单元。当某个步骤出现故障时，故障原因应能指向具体的责任主体，而非复杂的流程链。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。 对于那些会反复出现的6种故障场景，在修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 除了功能测试结果外，还需记录执行时间以及令牌或查询的成本。提前了解成本情况，可避免在系统从演示环境过渡到共享环境时出现意外账单。

分步指南：运用该技能从构思到落地实现

在按照分步指南操作时，首先需列出相关约定：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，这样操作人员无需查看整个系统结构即可进行审计。 需为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。若没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。

第一阶段：规划（提出正确的问题）

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

第二阶段：确定目标（选择最小可行产品级别）

在完成第二阶段的“识别与选择”阶段时，首先需明确合同规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明可追溯。 建议使用小型、可测试的单元而非庞大的脚本。当某个步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。 在完成第二阶段的“识别与选择”阶段时，首先需明确合同规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明可追溯。 应在功能结果旁记录执行时间以及代币或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。

第三阶段：蓝图设计（生成框架结构）

在将第三阶段的蓝图生成环节视为可度量的表面时，其效果最佳。在扩大范围之前，需记录一份最优案例、一个故障实例以及回滚说明。 应将配置信息与应用程序代码分开。环境文件、密钥存储和功能标志应集中存放于一个位置，以便操作人员无需查看整个架构即可进行审计。 需提供具有明确结构定义和清晰副作用标注的工具。主机在自动批准之前必须了解哪些调用会修改状态。

第四阶段：实施（严格遵循蓝图）

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

第五阶段：发布（上线前进行审计）

将第五阶段发布审计阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，先记录一份完美的操作日志、一个故障案例以及回滚说明。 相比庞大的脚本，应优先使用小型且可测试的单元。当某个步骤出现故障时，故障应指向单一责任主体，而非复杂的流程链。 应使用具有明确结构规范和清晰副作用标注的工具。主机需要在自动批准之前知道哪些调用会改变系统状态。 将第五阶段发布审计阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，先记录一份完美的操作日志、一个故障案例以及回滚说明。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。

实际案例：合同风险分析工具

在现实世界的合同阶段场景中，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 在网关处进行身份验证，在数据层进行重新授权。仅凭承载令牌并不足以界定租户边界。

案例：对现有研究代理进行审计

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

实际实现技巧（附伪代码）

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

标准代理循环（简化版）

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

budgets = Budgets(step=25, time=120, tokens=8000, cost=0.50)
context = build_initial_context()
permissions = load_permission_matrix()while not budgets.exhausted():
    response = model.generate(context, tools=typed_tool_schemas)
    if response.finish_reason == "stop":
        break
    if response.tool_calls:
        for tool_call in response.tool_calls:
            if not permissions.is_allowed(tool_call):
                observation = "Permission denied: " + tool_call.name
            else:
                # Execute with risk‑appropriate checks
                if permissions.risk(tool_call) == "external_write":
                    approval = request_human_approval(tool_call.draft)
                    if not approval:
                        observation = "Human rejected: " + tool_call.name
                    else:
                        observation = execute_tool(tool_call)
                else:
                    observation = execute_tool(tool_call)
            context.append(observation)
        # Optional compaction trigger
        if context.token_count() > budgets.token_per_turn:
            context = compact_context(context, preserve_approvals=True)
    else:
        # No tool calls, just final answer
        break

工具：从劣质到优质

在将工具从测试环境升级到正式环境时，应在修改代码之前明确输入参数、各步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏状态。除了功能测试结果外，还需记录执行时间以及令牌或查询的成本。提前了解成本情况，可避免在系统从演示环境过渡到共享环境时出现意外费用。

为提升缓存效率而进行的上下文分层

在缓存阶段的上下文分层中，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个架构即可进行审计。 在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。

Layer 0: System policies (stable prefix) → Cached
Layer 1: Agent skill definitions (rarely change) → Cached
Layer 2: User session instructions (per conversation) → Not cached
Layer 3: JIT‑retrieved tool outputs (fresh) → Not cached

部署您的代理工具：基础设施为何重要

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

这就是Aeza发挥作用的地方。

在“这是Aeza的阶段”中，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 相较于庞大的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。 在网关处进行身份验证，在数据层再次授权。仅凭承载令牌并不足以界定租户边界。 在“这是Aeza的阶段”中，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在流程从演示环境过渡到共享环境时出现意外账单。

为何选择 Aeza 处理您的代理工作负载？

在分析为何选择 Aeza 处理当前阶段的工作时，首先需列出相关合同条款：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 需为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。若没有这些记录，调试代理循环将会耗费大量时间。

安全性、可观测性及评估（切勿遗漏）

在处理安全可观测性与评估阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程与故障恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。

结论与下一步计划

您的即时行动方案

npx skills add DenisSergeevitch/agents-best-practices -g

git clone https://github.com/DenisSergeevitch/agents-best-practices.git ~/.codex/skills/

操作检查清单