AI Agent Engineer

AI Agent Engineer

安全、失败恢复与生产边界

14 min read

安全、失败恢复与生产边界

本节目标

你将为一个 CrewAI 系统画出信任边界，限制每个 Agent 和 Tool 的权限，区分重试、修订、恢复与人工接管，并理解检查点为什么不能单独保证“恰好执行一次”。最后，你会得到一份从本地演示走向生产的验收清单。

版本与证据边界

PyPI 在 2026-07-21 的最新稳定观察为 crewai==1.15.5，而本课程真实运行仍固定并复验 1.15.4；检查点、工具、Flow、Human Feedback 与遥测页面在 2026-07-21 补核。安全策略是工程建议，必须结合目标组织的数据分类、法规和基础设施复核。

从威胁模型开始

先列四项，而不是先写 Prompt：

  1. 资产：用户数据、内部知识、凭据、预算、文件、数据库和对外发送权限；
  2. 入口：用户文本、邮件、网页、PDF、Knowledge、Memory、Tool 返回和其他 Agent 产物；
  3. 信任边界：不同租户、开发与生产、模型提供商、浏览器/代码执行环境、外部 API；
  4. 高影响动作：付款、删除、发送、发布、修改权限、执行代码和写入生产数据库。

外部内容可能包含提示注入。可靠防护依赖工具白名单、严格参数 schema、最小权限、网络和文件隔离、额度限制及人工审批。Prompt 可以提醒模型，但不能提升系统层权限，也不能替代授权检查。

权限放在 Tool 边界，而不是 Agent 自述里

每个 Agent 只得到完成 Task 所需的工具。例如 writer 可以生成草稿，但不应拥有发送邮件工具；publisher 只接受已经通过审核且带审批令牌的草稿。Tool 在执行前仍需检查：

  • 调用者、租户和资源范围；
  • 参数类型、长度、枚举和路径；
  • 业务前置条件与审批状态；
  • 网络域名、文件目录和命令白名单；
  • 幂等键、速率、金额和总预算；
  • 输出是否需要脱敏或裁剪。

密钥通过环境或秘密管理系统注入，只在真正调用外部服务的代码边界读取。不要把密钥放入 Task 描述、Memory、Knowledge、事件、异常消息或示例文件。

失败分类决定处理方式

失败类型示例建议处理
输入无效缺字段、路径越界立即拒绝，返回可修正信息
权限拒绝Agent 无发送权限立即停止并记录，不换工具绕过
业务拒绝人工不批准发布合法终态，不自动重试
瞬时故障限流、短暂网络中断有上限退避重试，遵守服务端提示
永久故障资源不存在、接口已移除停止并修复配置或代码
内容不合格缺引用、schema 不通过有限修订，耗尽预算后人工接管
状态不兼容旧 schema 无法读取拒绝恢复或显式迁移，不猜字段

“再试一次”不是通用恢复策略。重试次数、等待时间、可重试异常和总预算必须在代码或配置中显式限制。

检查点、持久化与幂等性是三件事

  • 持久化保存 Flow state，使进程重启后仍能读取状态。
  • 检查点在约定边界保存执行进度，恢复时跳过已完成部分。
  • 幂等性确保同一业务动作重复请求不会产生第二次副作用。

官方 Checkpointing 页面在 2026-07-21 仍将该能力标为 early release，并介绍 CheckpointConfig 可为 Crew、Flow 或 Agent 配置检查点；checkpoint=True 使用默认的 ./.checkpoints，并在 Task 完成后保存。页面还列出 JSON 与 SQLite provider，以及通过 from_checkpoint(...) 恢复并跳过已完成 Task 的方式。具体签名需要在锁定版本验证，本课程离线项目没有执行这些 API。

官方页面同时说明，手动检查点写入采用 best-effort 方式：写入失败会记录，但执行可以继续。这意味着“开启检查点”不等于“每个副作用都已可靠记录”。如果发送邮件成功、而下一次检查点失败，恢复后可能再次发送。因此有副作用的 Tool 仍需要稳定幂等键，并在外部系统核对动作是否已完成。

一个安全的发布顺序可以是：

  1. 根据稳定的 operation_id + artifact_fingerprint 生成幂等键，不复用 Flow 执行 UUID；
  2. 在外部系统查询该键是否已有结果；
  3. 未完成才执行；
  4. 保存外部结果 ID；
  5. 更新 Flow state；
  6. 恢复时先查外部结果，再决定是否重试。

本课程项目的 publish_report 展示了同内容可恢复、不同内容拒绝覆盖和临时文件原子替换；它是本地文件示例，不等同于数据库或远程 API 的事务保证。

代码执行必须使用独立沙箱

2026-07-14 核验时，官方 Agents 页面说明 allow_code_execution、code_execution_mode 已废弃，并称 CodeInterpreterTool 已移除；但官方 Tools 页面仍列出 Code Interpreter Tool。两页存在可观察到的文档不一致，不能据此猜测某个锁定版本一定支持哪条路径。

工程结论不依赖这处矛盾：任何模型生成的代码都应在专用沙箱运行，并限制镜像、用户、CPU、内存、时长、网络、挂载目录和输出大小。不要直接在保存凭据、SSH 配置或研究数据的开发机环境执行。

人工审批是业务状态，不是一句自然语言

高风险动作应采用 preview → approve/reject → execute → verify。审批记录需要绑定：

  • 审批人身份与权限；
  • 要执行的确切参数和内容指纹；
  • 有效时间和一次性使用规则；
  • 对应 run_id 和资源；
  • 执行结果与外部记录 ID。

如果内容在审批后发生变化，旧审批应失效。人工拒绝必须进入明确终态，Agent 不得将其解释为“换个工具继续”。

@human_feedback 是暂停机制，不是授权服务

CrewAI 当前提供 @human_feedback 来暂停 Flow、收集反馈并在配置 emit 时路由 outcome；官方文档明确说明自由文本会由 LLM 映射到这些 outcome。它可以改善“等待谁的意见、下一步走哪条分支”的体验，但没有自动给出经过认证的审批人、目标资源、内容摘要、有效期、一次性使用或外部动作回执。

所以高影响 Tool 不应只检查 state.outcome == "approved"。把 Flow 的反馈结果当作需要验证的输入，由应用的审批服务签发绑定 actor_id + resource + canonical_payload_hash + expiry + nonce 的授权记录；执行层再次验证该记录、消费 nonce 并保存外部回执。Layer B 的 SQLite 例子只验证 receipt 恢复，不实现人类身份或审批服务，不能被误读为 HITL 授权实现。

生产发布清单

依赖与环境

  • 锁定 CrewAI、Python、模型 SDK 和工具依赖；
  • 开发、测试、生产使用不同凭据、存储和数据；
  • 启动时验证必需配置，但不打印秘密；
  • 明确记录内置遥测是否关闭、share_crew 是否禁用，以及观测数据要发送到哪里；
  • 分别记录匿名 telemetry、AMP tracing 与应用日志策略；优先用 CREWAI_DISABLE_TELEMETRY 关闭 CrewAI 匿名遥测，只有需要全局关闭时才使用 OTEL_SDK_DISABLED；锁定的 1.15.4 应在 Crew/Flow 实例显式 tracing=False 或按官方 CLI 管理持久 consent，不能只依赖环境变量值 false；
  • 检查 CREWAI_STORAGE_DIR 等路径的权限、容量、备份和恢复；
  • 记录部署制品与 schema 版本。

运行边界

  • 限制并发、最大步骤、重试、总时长、令牌和成本；
  • 为外部调用设置连接与读取超时；
  • 为连续失败设置熔断、降级和告警；
  • 默认从只读场景灰度，写操作需要更高门槛；
  • 定义人工接管、停止开关和回滚条件。

数据与审计

  • Knowledge、Memory、日志和检查点按租户隔离；
  • 敏感字段不采集或脱敏，设置保留和删除策略；
  • 私有或受监管环境默认关闭不需要的 CrewAI 外发遥测；若保留，验证字段、目的地、保留期和删除流程；
  • 未经明确隐私审批不得设置 share_crew=True，因为官方说明该模式会共享 goal、backstory、context 和 Task output 等详细执行数据；
  • 审计记录能回答谁、何时、对什么资源做了什么；
  • 第三方模型和观测后端的数据处理条款经过审查；
  • 删除流程覆盖索引、缓存、备份和衍生数据。

发布证据

  • 确定性测试、失败注入和恢复测试通过；
  • 锁定版本下的最小 Crew/Flow 集成测试通过；
  • 在启动测试中断言遥测策略生效，并防止升级后静默改变外发范围；
  • 回归集达到任务、安全、成本和延迟门槛；
  • 已演练密钥轮换、依赖回滚和人工接管；
  • 已明确哪些风险仍未验证。

框架不能替你保证什么

CrewAI 可以提供 Agent、Task、Crew、Flow、工具、事件和持久化等构件，但不会自动证明模型输出正确、工具安全、记忆合规、多 Agent 优于单 Agent，或一次恢复不会重复外部副作用。验收必须针对你的数据、权限、终态和故障模式。

动手实践

为“读取客户邮件、生成回复并发送”的系统完成以下设计：

  1. 画出邮件服务、模型、Knowledge、日志和发送 Tool 的信任边界；
  2. 设计 drafted、awaiting_approval、approved、sent、rejected、human_review 状态；
  3. 定义审批内容指纹和发送幂等键；
  4. 注入“发送成功但检查点失败”的故障；
  5. 验证恢复后不会重复发送；
  6. 验证邮件正文中的提示注入无法扩大工具权限。

掌握检查

  • 能说明 Prompt 不能替代工具权限和参数校验。
  • 能区分可重试、不可重试、可修订和人工拒绝。
  • 能解释检查点、持久化和幂等性各自解决的问题。
  • 能为有副作用的 Tool 设计重复恢复测试。
  • 能说明默认遥测、AMP tracing、share_crew、CrewAI 专用关闭变量和全局 OTEL_SDK_DISABLED 的不同边界。
  • 能列出 CrewAI 演示进入生产前仍需补齐的证据。

下一步

先用 离线研究简报 Flow 建立合同，再用 真实 CrewAI 持久化 Flow 注入 receipt 后崩溃并验证恢复。

主要参考资料

Checkpointing、Flow、Tool、Human Feedback、Telemetry 与 Tracing 页面复核日期：2026-07-21；Agents/Code Interpreter 文档间的历史不一致记录保留 2026-07-14 作为证据边界；PyPI 包复核日期：2026-07-21。

Backlinks