AI Agent Engineer

AI Agent Engineer

测试、评测与可观测性

12 min read

测试、评测与可观测性

本节目标

你将学会把“Agent 看起来能工作”改写成可重复的验收条件：先用确定性测试覆盖数据、工具、Task 和 Flow，再用多次模型运行评估非确定性质量，最后用事件和版本信息解释失败发生在哪里。

动态资料边界

PyPI 在 2026-07-21 的最新稳定观察为 crewai==1.15.5，而本课程 Layer B 的经测试基线仍是 1.15.4。官方测试命令、默认模型和提供商限制都可能变化。运行真实项目时，先查看锁定版本的 crewai test --help，不要从本笔记推断未来 CLI 行为。

为什么一次成功演示不算验收

LLM 输出会受模型版本、采样、上下文、工具返回和网络状态影响。一个示例成功，只能说明“这一轮没有暴露问题”，不能证明：

  • 失败输入能安全停止；
  • 工具不会越权或重复产生副作用；
  • 引用真的支持结论；
  • Flow 在第二次尝试后会终止；
  • 依赖或 Prompt 更新后没有回归；
  • 成本和延迟满足生产预算。

因此需要把确定性业务控制和概率性内容质量分开验证。

四层测试与评测

第一层：纯函数与 schema 单元测试

不调用模型，覆盖最稳定也最便宜的部分：

  • 输入字段、类型、长度和未知字段拒绝；
  • Tool 参数白名单与权限检查；
  • Task 输出 schema 和来源 ID；
  • Flow 状态迁移、尝试上限和终态；
  • 幂等发布、重复恢复与不同内容拒绝覆盖；
  • 错误分类和哪些错误可以重试。

这些测试应在普通 Python 和 python -O 下都有效，不要把关键校验写在 assert 中，因为优化模式会移除普通断言。本课程 Layer A 的 39 个测试就是这一层的示例；Layer B 另有 9 项真实 CrewAI runtime 测试，两组结果不能合并成一个模糊数字。

第二层：Agent 或 Task 离线评测

为单个 Task 固定输入和判定器，检查：

  • 是否生成可解析的结构化输出；
  • 是否只使用允许来源；
  • 缺证据时是否表达未知；
  • 是否出现禁止内容或越权工具意图；
  • 同一输入多次运行的通过率和主要失败类型。

模型桩适合验证控制逻辑，但不能代表真实模型质量。录制响应可以降低成本，却可能掩盖模型升级后的变化；需要明确标注录制时间、模型和 SDK 版本。

第三层：Crew 轨迹评测

检查协作过程，而不只看最终答案：

  • Task 是否按允许顺序执行；
  • 每个 Agent 是否只使用自己的工具；
  • 失败是否路由到修订或人工接管；
  • 工具调用次数、总步骤、令牌和时间是否在预算内；
  • 每条关键结论能否追溯到来源和中间产物。

多 Agent 之间“聊得很热闹”不是质量指标；轨迹应证明分工真的带来独立产物或校验价值。

第四层：小规模真实集成与在线评测

在锁定模型、依赖和数据版本后，用受控凭据运行少量端到端样本。逐步增加并发和真实数据，记录质量、成本、延迟与安全。高风险写操作先用预览或沙箱替代，达到发布门槛后才开放。

评测集如何设计

一个有效评测集至少包含：

  1. 正常输入；
  2. 边界值和空值；
  3. 缺少来源或无法回答；
  4. 外部文档中的提示注入；
  5. 工具超时、限流和权限拒绝；
  6. 重复运行与检查点恢复；
  7. 人工拒绝；
  8. 不同租户或权限的数据隔离；
  9. 极长上下文；
  10. 旧 schema、旧知识版本或不兼容状态。

每条样本至少记录：样本 ID、输入版本、期望终态、允许工具、禁止行为、必须引用、最大尝试次数和判定方式。需要主观判断时，先写评分 rubric，并用人工样本校准判定器。

指标与发布门槛

维度指标示例门槛设计要点
任务任务成功率、终态正确率分场景报告，不只看总体平均值
事实引用支持率、未知项识别率关键结论必须逐条可追溯
工具工具选择准确率、参数通过率越权调用应单独计为严重失败
可靠性重试后成功率、重复副作用率重复副作用通常必须为 0
安全注入成功率、秘密泄露率高风险违规不能被平均质量分抵消
运行P50/P95 延迟、步骤和成本同时给出样本规模和版本
人工接管率、误拒率、审核耗时接管本身可能是正确终态

先定义红线，再定义平均质量。例如“引用支持率 ≥ 某阈值”不能抵消一次真实凭据泄露。阈值必须来自具体业务风险和基线，而不是照抄别人的数字。

CrewAI 自带测试能力如何定位

官方 Testing 页面提供 crewai test 作为 Crew 测试入口。2026-07-21 页面仍描述了默认迭代、默认模型及当前提供商限制；这些是易变实现事实。本课程没有真实密钥，也没有执行该命令。采用它时应：

# 在真实项目的已激活 venv 中先确认当前 CLI
crewai test --help  # 查看锁定版本实际提供的参数、默认行为和可用测试入口。
 
# 确认成本、模型和样本后再运行
crewai test  # 执行框架级 Crew 测试；仍需用应用测试覆盖安全与业务合同。

框架命令可以补充真实 Crew 评测，但不能替代你的 schema、权限、幂等性和 Flow 路由单测。

可观测性：为失败保留可解释证据

每次运行生成唯一 run_id，事件至少记录：

  • 事件序号、类型和时间；
  • Crew、Agent、Task 与 Tool 的稳定 ID；
  • 输入输出的 schema 版本和安全摘要；
  • 工具成功、错误类别、重试与耗时；
  • 路由决定、审批人或人工接管原因；
  • 依赖、模型、Prompt、工具 schema、Knowledge 和评测集版本；
  • 最终状态、成本与关键质量判定。

不要把完整 Prompt、密钥、个人数据或工具原始响应无差别写入日志。可观测性系统自身也是一个数据接收端，需要最小权限、脱敏、保留期限和访问审计。

CrewAI 的内置 tracing 与匿名 telemetry 是不同通道。当前官方 tracing 页面说明启用 tracing 后可看到 Agent 决策、Tool 使用以及 LLM 调用的 prompts/responses；因此“为了排障打开 tracing”本身是一项数据外发与访问控制决策。Layer B 仅在锁定版本的 fixture 上以 tracing=False 验证运行时控制面，且没有做网络抓包；它不能证明真实部署、插件或 exporter 没有额外数据出口。把 trace 目的地、字段最小化、访问角色、保留期和抽样策略纳入发布前测试。

官方 Event Listeners 页面提供基于事件总线的监听机制，并以 BaseEventListener 等概念展示如何订阅 CrewAI 事件。事件类型与导入路径可能随版本变化；真实接入前要在锁定版本做最小导入测试。监听器失败也不应悄悄改变核心业务语义。

一次回归如何定位

  1. 确认样本、依赖、模型、Prompt、工具 schema 和知识索引的版本；
  2. 找到首次出现失败的事件与 Task；
  3. 区分模型输出错误、工具错误、路由错误和判定器错误；
  4. 用固定输入重放最小失败单元；
  5. 一次只改变一个主要变量；
  6. 新增能重现问题的测试，再验证修复没有破坏其他场景。

如果观测数据不足以定位，就应明确写“当前无法证明原因”，而不是根据最终文本猜测。

动手实践

以研究简报 Crew 为例，设计 12 条评测样本：4 条正常、3 条缺证据、2 条工具故障、2 条提示注入、1 条重复恢复。为每条样本写出：

  • 期望终态；
  • 允许调用的工具；
  • 必须出现的来源 ID；
  • 最大尝试次数；
  • 一个自动判定和一个人工抽查项。

然后运行 离线研究简报 Flow 的三种测试模式，解释为什么普通模式、-O 和 warnings-as-errors 各自提供不同证据。

掌握检查

  • 能区分确定性测试、模型评测、轨迹评测与在线评测。
  • 能为每条评测样本指定期望终态和禁止行为。
  • 能同时报告质量、可靠性、安全、成本与延迟。
  • 能用运行事件和版本信息复现一次失败。
  • 知道 crewai test 不能替代业务控制和安全测试。

下一步

测试暴露问题后，还需要决定系统如何安全停止、恢复和上线：安全、失败恢复与生产边界。

主要参考资料

资料获取日期：2026-07-21。

Backlinks