---
title: "Agent Eval Trace"
created: 2026-05-26
type: concept
tags: ["agent-evaluation", "trace", "logging"]
sources: ["mini-agent-harness"]
---

# Agent Eval Trace

> Agent 评测中每一步工具调用、参数、返回值的结构化执行记录。

## 定义

Trace 是 [[agent-harness-mini|mini harness]] 的核心模块之一，记录了 Agent 在任务执行过程中的每一步操作。它是将 Agent 行为从"黑盒"变为"白盒"的关键。

## 结构

典型的 trace 条目：

```json
{
  "case_id": "case_001",
  "trace": [
    {
      "tool": "list_files",
      "arguments": {"path": "."},
      "result": ["README.md", "config.md"]
    },
    {
      "tool": "read_file",
      "arguments": {"path": "README.md"},
      "result": "本项目支持本地启动、基础登录和配置管理。"
    }
  ],
  "answer": "当前 README 没有插件系统相关说明...",
  "grade": {"success": true, "reason": "..."}
}
```

## Trace 的诊断价值

Trace 让问题定位变得精确：

- **未调用关键工具** → 工具选择/理解问题
- **调用了但参数错误** → 参数填写问题
- **调用了但忽略了返回值** → 结果读取问题
- **反复调用无关工具** → 轨迹效率问题
- **答案超出工具返回内容** → 幻觉/编造问题

## 与日志的区别

| 维度 | Trace | 传统 Log |
|------|-------|---------|
| 粒度 | 每个 tool call | 应用级事件 |
| 结构化 | JSON schema | 自由格式 |
| 目的 | 评测分析 | 调试/监控 |
| 关联 | 与 case + grade 绑定 | 独立记录 |

## 相关页面

- [[agent-eval-grader]] — 使用 trace 进行评分
- [[agent-eval-case-design]] — 设计可追踪的评测用例
- [[agent-harness-mini]] — 包含 trace 模块的完整 harness