Skip to content

三窗格轨迹评估 (eval_trace)

eval_trace 显示会将一条智能体轨迹拆分为三个同步窗格（推理、函数调用和最终答案），让评估者一眼看清智能体思考了什么、做了什么、产出了什么。专为持续评估而构建。

eval_trace 显示会将单条智能体轨迹拆分为三个同步窗格：推理、函数调用和最终答案。 评估者可以并排看到智能体思考了什么、做了什么、产出了什么，这适合持续评估的场景，在这类场景中新轨迹不断到来，必须被迅速判定。

与把交错轨迹堆叠在一列里的纵向智能体轨迹显示不同，eval_trace 将一条轨迹分解为三个语义组成部分，因此无需滚动即可看清智能体行为的结构。

三窗格 eval_trace 显示一条被拆分为推理、函数调用和最终答案窗格的智能体轨迹

快速开始

从仓库根目录运行随附的示例：

bash
python potato/flask_server.py start examples/agent-traces/continuous-eval/config.yaml -p 8000

该示例还提供了一个目录监视变体（config-watch.yaml），用于摄入投放进来的轨迹文件。

配置

yaml
instance_display:
  layout:
    direction: vertical      # task header above the (internally horizontal) panes
    gap: 12px
  fields:
    - key: task_description
      type: text
      label: "Task"
 
    - key: trace             # the field holding the agent trace
      type: eval_trace
      label: "Agent Trace"
      display_options:
        pane_labels: ["Reasoning", "Function Calls", "Final Answer"]
        show_step_numbers: true
        collapse_long_outputs: true
        max_output_lines: 12
        link_steps: true

选项

选项默认值说明
pane_labels["Reasoning", "Function Calls", "Final Answer"]三个窗格的标题。
show_step_numberstrue在推理卡片和调用卡片上显示 #N 步骤编号。
collapse_long_outputstrue将长度超过 max_output_lines 的工具结果折叠成可展开的区块。
max_output_lines20折叠结果的行数阈值。
link_stepstrue跨窗格高亮：点击某张卡片会高亮其他窗格中与之关联的卡片。
compactfalse更紧凑的内边距和间距。

数据格式

eval_trace 接受与智能体轨迹显示相同的轨迹格式。最常见的是一组 {speaker, text} 步骤：

json
{
  "id": "eval_001",
  "task_description": "Find a vegan lasagna recipe.",
  "trace": [
    {"speaker": "Agent (Thought)",      "text": "I'll search for a highly-rated recipe."},
    {"speaker": "Agent (Action)",       "text": "web_search(query='vegan lasagna')"},
    {"speaker": "Environment",          "text": "10 results found..."},
    {"speaker": "Agent (Final Answer)", "text": "Here's a great recipe: ..."}
  ]
}

thought/action/observation 和 step_type/content 格式也受支持。

步骤如何映射到窗格

步骤（类型从 speaker 或 label 推断）窗格
Thought、推理、规划、system推理
Action、tool、function、call函数调用（相邻的 Environment/结果嵌套在该调用之下）
Final Answer、send_message、respond、finish，或在没有匹配项时取最后一个动作最终答案

要设置明确的最终答案，请用一个 speaker 匹配答案模式的步骤（例如 "Agent (Final Answer)"）或一个 send_message(...) 动作来结束轨迹。

步骤关联

步骤会被分组为逻辑循环：一个想法以及它触发的调用共享同一个步骤索引。在 link_steps: true 时，点击任意卡片会高亮各窗格中共享该索引的每一张卡片，从而让你将一个想法追溯到它产生的动作。

持续评估

将 eval_trace 与 Potato 的任意运行时摄入传输方式搭配使用，使轨迹在到达时即被评估：

  • Webhook 和 SSE —— trace_ingestion: {enabled: true} 会暴露一个 webhook 端点，并将新轨迹流式推送给标注者。
  • Langfuse 轮询 —— 在 trace_ingestion.sources 下添加一个 langfuse 源。
  • 目录监视 —— data_directory 加上 watch_data_directory: true 会摄入投放进来的 .json 和 .jsonl 文件。

运行时新增的轨迹可立即分配给标注者。将其与分诊队列结合使用，可将出错或低分的轨迹推到最前面。

注意事项与限制

  • eval_trace 仅用于显示；它本身不收集任何标注。请像示例那样，将它与诸如 reasoning_quality、tool_use_correctness 或 answer_helpfulness 之类的标注方案搭配使用。
  • eval_trace 不支持跨度标注。如果你需要在轨迹文本上进行跨度高亮，请使用智能体轨迹或 code 显示。

相关内容

有关实现细节，请参阅源文档。