# Evaluation and Observability

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

## Evaluation Pyramid

```text
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

建议每次运行至少记录：

```yaml
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](../research/evaluation/k1412-agent-evaluation-v1.md)。