agent/docs/04-evaluation-observability.md

Evaluation and Observability

Agent 评估要同时看结果、过程和运行成本。

Evaluation Pyramid

Human review
Scenario tests
Tool and integration tests
Schema and unit checks

Metrics

Task Quality

• Success rate: 任务完成率。
• Correctness: 事实、代码或业务结果是否正确。
• Completeness: 是否遗漏关键步骤。
• Helpfulness: 输出是否解决用户问题。

Process Quality

• Tool accuracy: 工具是否选对，参数是否正确。
• Recovery rate: 工具失败后是否能恢复。
• Plan stability: 计划是否合理更新。
• Evidence coverage: 结论是否有证据支撑。

Operational Quality

• Latency: 总耗时和关键路径耗时。
• Cost: token、API、工具调用成本。
• Reliability: 重试、超时、失败率。
• Safety: 高风险动作是否经过正确控制。

Test Set Design

一个好的评估集应该包含：

• 常规成功路径。
• 边界条件。
• 信息不足的任务。
• 工具失败或返回异常。
• 用户指令冲突。
• 高风险动作。
• 历史回归样例。

Trace Schema

建议每次运行至少记录：

run_id:
task:
user_goal:
constraints:
context_sources:
plan:
tool_calls:
observations:
final_output:
verification:
metrics:
errors:
follow_ups:

Review Questions

• Agent 是否真的完成了用户目标？
• 是否有未验证的关键事实？
• 是否调用了不必要的工具？
• 是否错过了更便宜或更稳定的路径？
• 是否产生了不可恢复的副作用？
• 失败时，日志是否足够定位原因？

Versioned Evaluation Contract

真实 Agent 评测还必须固定 task/fixture、模型、系统 prompt、工具 schema、工作区镜像、 上下文和预算。最终成功由独立 validator 判断，而不是由 Agent 的完成声明判断。

对 baseline 和 variant 做配对比较时，至少分开报告：

• baseline fail -> variant pass: gain；
• baseline pass -> variant fail: regression；
• both pass；
• both fail；
• provider/infrastructure error。

平均成功率不能掩盖 regressions，安全违规和 false completion 也不能被成本收益抵消。

当前可执行设计见 K1412 Agent Evaluation v1。