agent-insight 0.5.1 → 0.5.2

package/.next/standalone/Evaluation_and_Research/agent_evaluator_research_qna_4.md

@@ -0,0 +1,1228 @@
+# Agent 评估器调研问答 4
+
+调研日期：2026-07-07
+
+这份文档用于继续记录 `agent_evaluator_industry_research.md` 里的细节问题。上一份问答见 `agent_evaluator_research_qna_3.md`。
+
+## Q9：失败定位 / 根因归因的评估逻辑是什么？它和我们项目里的 AgentDebug 有什么区别？
+
+### 简短结论
+
+失败定位 / 根因归因作为一个“预置评估器”时，核心不是做一次完整诊断，而是把一条失败或低质量 trace 结构化地回答成：
+
+```text
+这次失败主要发生在哪一步？
+真正的上游原因是什么？
+它属于哪类 agent 能力问题？
+证据是什么？
+这个结论有多可信？
+```
+
+它的价值在于让大批量评测结果可以被聚合、统计和回归比较。例如：
+
+```text
+本周 42% 的失败来自工具参数错误
+18% 来自检索上下文不足
+12% 来自父 agent 没有整合子 agent 结果
+某次 prompt 改动后 planning 类根因下降了 30%
+```
+
+而 AgentDebug 更像是“单条 trace 的深度诊断系统”。它读取一条具体执行记录，基于 Trace / Span / 调用链 / 上下文证据，输出比较完整的诊断报告、问题卡片、模块级归因、证据链和修复建议。
+
+所以两者不是替代关系：
+
+```text
+失败定位 / 根因归因评估器：
+  面向批量评测、可计分、可聚合、可比较。
+
+AgentDebug：
+  面向单条异常执行的深度解释、复盘和修复指导。
+```
+
+更推荐的产品关系是：
+
+```text
+预置评估器先做轻量根因归因；
+高严重度、低置信度或需要人工复盘的样本，再跳转到 AgentDebug 深入诊断。
+```
+
+### 这个评估器到底评什么？
+
+它评的不是“最终答案好不好”，而是：
+
+```text
+当一次 agent 执行失败、低分或异常时，系统能不能把失败归因到正确的步骤、模块和根因类别。
+```
+
+可以把它理解成任务完成度之后的二级评估：
+
+| 一层问题 | 回答 |
+| --- | --- |
+| Task Completion | 任务有没有完成？ |
+| Failure Localization / Root Cause Attribution | 如果没完成，主要为什么没完成？失败源头在哪里？ |
+
+例如：
+
+```text
+最终失败：用户要求修改代码并跑测试，但最后没有修复 bug。
+
+普通任务完成度：
+  failed
+
+根因归因：
+  root_cause_category = tool_invocation_error
+  critical_step = 7
+  evidence = 测试命令参数错误，导致 agent 误以为目标测试已通过
+  downstream_effect = 后续总结基于错误测试结果，产生 false success
+```
+
+这个指标的意义不是替代任务完成度，而是让失败样本“可解释、可分桶、可优化”。
+
+### 输入是什么？
+
+一个根因归因评估器通常需要这些输入：
+
+```text
+task:
+  用户原始任务、约束、期望输出
+
+trace:
+  完整执行轨迹，包括 LLM 思考/回复、工具调用、工具结果、子 agent 调用、错误、重试
+
+final_output:
+  最终回答或最终状态
+
+outcome_signal:
+  任务完成度、人工标签、自动 evaluator 分数、报错状态等
+
+optional_reference:
+  参考答案、期望工具调用、期望步骤、标准 trace、人工根因标签
+```
+
+其中 `outcome_signal` 很关键。因为根因归因通常是在“已经知道这条 trace 有问题”之后发生的。如果完全没有失败信号，评估器会很难判断要归因什么。
+
+在 Agent Insight 里，输入可以来自：
+
+- Execution 基本信息。
+- Trace / Span / 节点列表。
+- 工具调用与返回结果。
+- 子 agent execution tree。
+- 现有轨迹评估结果。
+- AgentDebug 已生成的诊断报告。
+- 人工标注或评测集里的 expected root cause。
+
+### 中间评估逻辑
+
+#### 1. 先判断是否真的失败
+
+第一步不是直接找根因，而是判断这条 trace 是否需要归因：
+
+```text
+success:
+  任务成功，无需根因归因，可输出 n_a。
+
+soft_failure:
+  没有显式报错，但结果不完整、偏题、未满足约束。
+
+hard_failure:
+  工具报错、执行中断、超时、权限失败、链路异常。
+
+ambiguous:
+  结果是否失败不明确，需要依赖人工标签或更强 evaluator。
+```
+
+如果没有先判断失败类型，根因归因容易变成“每条 trace 都硬找问题”，导致误报。
+
+#### 2. 把 trace 切成可归因节点
+
+根因归因要有定位对象。常见粒度包括：
+
+```text
+span:
+  一次模型调用、一次工具调用、一次子 agent 调用、一个系统节点。
+
+step:
+  对用户可解释的一步行为，例如“读取文件”“调用搜索工具”“执行测试”。
+
+turn:
+  一轮 assistant / tool / user 交互。
+
+phase:
+  计划、检索、工具调用、结果整合、最终回答等阶段。
+```
+
+在产品里建议同时保留两层：
+
+```text
+machine_location:
+  spanId / traceStepIndex / executionId，用于跳转和聚合。
+
+human_location:
+  第几步、节点名称、简短行为摘要，用于用户理解。
+```
+
+#### 3. 区分“症状节点”和“根因节点”
+
+这是根因归因最重要的一步。
+
+很多失败暴露在下游，但原因在上游：
+
+```text
+症状：
+  最终答案错误。
+
+可能根因：
+  第 3 步检索结果不相关。
+  第 5 步工具参数错了。
+  第 7 步把工具返回结果读反了。
+  第 9 步子 agent 给出正确结论，但父 agent 没有采用。
+```
+
+所以 evaluator 不能只定位最后一个失败 span。它应该沿 trace 回看：
+
+```text
+哪个最早的关键偏差足以解释后续失败？
+哪个错误如果被修复，最终结果大概率会变好？
+哪个节点是上游原因，而不是下游表现？
+```
+
+这也是为什么 AgentEval 这类方法会强调把 agent execution 建成 DAG：根因往往要通过依赖传播来判断，而不是只看线性最后一步。
+
+#### 4. 对根因类别做标准化分类
+
+为了让结果可统计，根因类别必须稳定。建议不要只输出自然语言，而要输出枚举标签。
+
+适合 Agent Insight 的第一版 taxonomy 可以是：
+
+| 根因类别 | 含义 |
+| --- | --- |
+| `planning_error` | 任务拆解、步骤顺序、执行策略错误 |
+| `memory_context_error` | 忘记用户约束、上下文继承错误、状态记忆错误 |
+| `retrieval_error` | 检索不到、检索不相关、上下文召回不足 |
+| `tool_selection_error` | 选错工具、漏用工具、不该用工具却用了 |
+| `tool_invocation_error` | 工具参数、格式、调用时机错误 |
+| `tool_response_handling_error` | 工具结果读取、解释、整合错误 |
+| `verification_error` | 没有验证、误读测试结果、false success |
+| `safety_policy_error` | 违反安全、合规、权限、用户约束 |
+| `multi_agent_routing_error` | 子 agent 路由、交接、整合错误 |
+| `loop_no_progress` | 重复尝试、无进展、非终止 |
+| `system_infra_error` | 环境、权限、网络、依赖、外部服务异常 |
+| `instruction_following_error` | 没有遵循显式指令或输出格式 |
+| `unknown` | 证据不足，无法可靠归因 |
+
+这个 taxonomy 可以和现有 AgentDebug 的五模块对齐：
+
+| AgentDebug 维度 | 评估器根因类别示例 |
+| --- | --- |
+| Memory | `memory_context_error` |
+| Reflection | `verification_error`, `loop_no_progress` |
+| Planning | `planning_error`, `multi_agent_routing_error` |
+| Action | `tool_selection_error`, `tool_invocation_error`, `tool_response_handling_error` |
+| System | `system_infra_error`, `safety_policy_error` |
+
+区别在于：AgentDebug 的维度更像诊断坐标系，适合解释单条 trace；预置评估器的类别更像统计标签，适合批量聚合和回归分析。
+
+#### 5. 标注 root / contributing / downstream
+
+真实失败经常不是单点问题，而是一条链：
+
+```text
+第 2 步检索不相关
+  -> 第 4 步基于错误上下文制定计划
+  -> 第 6 步调用了错误工具
+  -> 最终答案错误
+```
+
+所以输出不应该只有一个 `root_cause`。更合理的是给每个问题一个角色：
+
+```text
+root:
+  最主要上游原因。
+
+contributing:
+  加重失败的问题，但不是第一根因。
+
+downstream:
+  下游症状或传播结果。
+```
+
+这和 AgentDebug 现有的 `AgentDebugFindingIssueRole` 设计是相通的。差别是，预置评估器可以输出更轻量的 issue list，AgentDebug 输出更完整的诊断报告。
+
+#### 6. 生成证据和置信度
+
+每个归因都必须带证据，否则无法被用户信任，也无法复核。
+
+建议输出：
+
+```text
+evidence:
+  对应 span / step 的事实摘要
+
+evidence_span_ids:
+  可跳转的 spanId / traceStepIndex
+
+reasoning:
+  为什么这个证据支持该根因
+
+confidence:
+  0-1 置信度
+```
+
+置信度可以根据这些因素调整：
+
+- 是否有显式工具错误。
+- 是否有人工 expected label。
+- trace 是否完整。
+- evaluator 之间是否一致。
+- 根因是否能解释后续失败链。
+- 是否存在多个同样合理的原因。
+
+### 输出应该是什么？
+
+建议输出一个紧凑、可聚合的 JSON，而不是长篇诊断报告：
+
+```json
+{
+  "score": 0.78,
+  "label": "failed_with_attribution",
+  "failure_type": "soft_failure",
+  "root_cause_category": "tool_response_handling_error",
+  "critical_steps": [
+    {
+      "step_index": 6,
+      "span_id": "span_abc",
+      "role": "root",
+      "category": "tool_response_handling_error",
+      "summary": "agent ignored the tool result indicating the file was unchanged",
+      "evidence": "tool output reported no matching file, but the next step claimed the edit succeeded",
+      "confidence": 0.82
+    }
+  ],
+  "downstream_effects": [
+    "final response reported success without verification"
+  ],
+  "suggested_fix": "Add verification after file-edit tool calls and treat no-op tool responses as blocking.",
+  "is_skill_attributable": true,
+  "confidence": 0.78
+}
+```
+
+字段建议：
+
+| 字段 | 含义 |
+| --- | --- |
+| `score` | 归因质量或根因明确度，0-1 |
+| `label` | success / failed_with_attribution / failed_unknown / n_a |
+| `failure_type` | soft_failure / hard_failure / ambiguous |
+| `root_cause_category` | 标准化根因类别 |
+| `critical_steps` | 根因、贡献因素、下游症状对应的步骤 |
+| `evidence` | 可复核证据 |
+| `confidence` | 归因置信度 |
+| `suggested_fix` | 面向优化的建议 |
+| `is_skill_attributable` | 是否更可能通过 skill / prompt / evaluator 改进解决 |
+
+### 怎么证明这个评估器是好的？
+
+根因归因评估器本身也需要被验证。推荐三类证明方式。
+
+#### 1. 和人工标注对齐
+
+构造一批失败 trace，由专家标注：
+
+```text
+是否失败
+根因类别
+关键步骤 / span
+root / contributing / downstream
+证据是否充分
+```
+
+然后衡量 evaluator：
+
+| 验证指标 | 含义 |
+| --- | --- |
+| failure detection precision / recall | 是否能发现真失败，少误报 |
+| root cause category accuracy / F1 | 根因类别是否和人工一致 |
+| localization accuracy / span-F1 | 定位步骤是否接近人工标注 |
+| evidence precision | 引用证据是否真的支持结论 |
+| inter-rater agreement | evaluator 与人类、多名人类之间一致性 |
+
+#### 2. 看归因是否能指导修复
+
+更强的证明方式是：
+
+```text
+按 evaluator 归因修复 prompt / skill / tool schema / routing 逻辑后，
+同类失败率是否下降。
+```
+
+例如 evaluator 发现大量失败来自 `tool_response_handling_error`，团队增加工具结果校验后，同一评测集上的 false success 下降。这比单纯“判断看起来合理”更有说服力。
+
+#### 3. 看批量统计是否稳定
+
+如果 evaluator 有意义，那么在同一批样本上重复运行，根因分布应该相对稳定；在不同版本 agent 上运行，变化应该能解释产品改动。
+
+例如：
+
+```text
+版本 A:
+  planning_error 35%
+  tool_invocation_error 22%
+
+版本 B 引入 planner prompt 后:
+  planning_error 18%
+  verification_error 26%
+```
+
+这种变化如果能和实际改动对应，说明 evaluator 具备监控和回归分析价值。
+
+### 它和 AgentDebug 的区别
+
+可以从定位、粒度、输出、成本、使用场景五个方面理解。
+
+| 维度 | 失败定位 / 根因归因评估器 | AgentDebug |
+| --- | --- | --- |
+| 产品定位 | 预置 evaluator，服务评测中心、批量回归、质量统计 | 智能诊断能力，服务单条 trace 的深入排查 |
+| 主要问题 | “这一批失败主要因为什么？”“这条样本可归到哪个根因桶？” | “这条执行到底哪里出了问题？证据链是什么？怎么修？” |
+| 输入 | trace + outcome signal + 可选参考标签 | 单条 execution trace / interactions / trace bundle |
+| 输出 | 短 JSON、分数、类别、关键步骤、证据、置信度 | 完整诊断报告、issue、finding、rootCause、phase1Grid、trajectoryFindings |
+| 粒度 | 更标准化、可聚合 | 更细、更解释性、更适合阅读和复盘 |
+| 成本 | 应尽量轻量，可规则 + LLM 混合 | 可以更重，当前会调用 agent-debug-diagnosis skill 和 LLM |
+| 适用场景 | 离线评测、版本对比、失败分桶、仪表盘统计 | 单条异常深挖、研发排障、问题复盘、生成修复建议 |
+| 稳定性要求 | 高，需要 schema 固定、标签稳定 | 可保留更丰富的自然语言解释 |
+| 与用户交互 | 通常不需要交互，自动跑 | 适合用户点击进入详情页查看 |
+
+一句话：
+
+```text
+根因归因评估器是“可统计的轻量归因标签”；
+AgentDebug 是“可阅读的深度诊断报告”。
+```
+
+### AgentDebug 现在已经覆盖了什么？
+
+从当前项目实现看，AgentDebug 已经具备很强的诊断能力：
+
+- `runAgentDebugDiagnosis()` 会把 interactions 转成 debug turns。
+- 使用 `agent-debug-diagnosis` skill 生成结构化认知根因报告。
+- 输出 `issues`、`findings`、`rootCause`、`phase1Grid`、`stepRecords`。
+- 用 Memory / Reflection / Planning / Action / System 做模块级归因。
+- 支持 `root` / `contributing` / `downstream` 角色。
+- 已经有确定性的 `trajectory-detector` 用于识别循环、无进展、振荡、重复等轨迹级问题。
+- 诊断结果面向单条 trace 的证据链、修复建议和用户可读解释。
+
+所以，如果只是问“Agent Insight 有没有根因诊断能力”，答案是：
+
+```text
+有，而且 AgentDebug 已经是比较完整的深度诊断实现。
+```
+
+但如果问“是否已经有一个适合放进预置评估器列表里的根因归因 evaluator”，答案更接近：
+
+```text
+还没有完全产品化成 evaluator。
+```
+
+因为 evaluator 还需要更强调：
+
+- 输出短、稳定、可入库。
+- 标签枚举固定。
+- 分数可比较。
+- 大批量运行成本可控。
+- 能出现在评测报表里。
+- 能和其他 evaluator 一起排序、筛选、聚合。
+
+### 推荐怎么在 Agent Insight 里落地
+
+建议不要另起一套和 AgentDebug 完全平行的复杂诊断系统，而是做成“三层结构”。
+
+#### 第一层：规则预筛
+
+先用低成本规则提取明显信号：
+
+```text
+tool error
+timeout
+permission denied
+empty retrieval
+repeated same tool call
+no progress loop
+subagent result ignored
+final answer without verification
+```
+
+这一层可以复用当前 AgentDebug 的 `trajectory-detector` 思路，也可以复用 Trace / Span 的结构化字段。
+
+#### 第二层：轻量 LLM 归因
+
+把规则预筛结果、关键 span 摘要、任务目标和最终结果喂给 judge，让它只输出固定 schema：
+
+```text
+failure_type
+root_cause_category
+critical_steps
+evidence
+confidence
+suggested_fix
+```
+
+注意这里不需要生成完整诊断长文，目标是“评估器输出”，不是“诊断报告”。
+
+#### 第三层：AgentDebug 深挖
+
+当满足以下条件时，再触发或推荐 AgentDebug：
+
+```text
+root_cause_category = unknown
+confidence < 0.6
+severity = high
+用户点击查看详情
+同类失败突然增多
+需要生成 skill 改进建议
+```
+
+这样可以兼顾成本和深度：
+
+```text
+大多数样本用 evaluator 快速归因；
+少数重要样本用 AgentDebug 深度诊断。
+```
+
+### 和现有轨迹评估、SkillIssue 的关系
+
+当前轨迹评估更像对执行过程质量打分，例如完整性、工具选择、冗余等。根因归因评估器可以作为它的下游解释层：
+
+```text
+轨迹评估：
+  这条 trace 分数低。
+
+根因归因：
+  分数低主要因为 tool_response_handling_error，关键步骤是第 6 步。
+```
+
+`SkillIssue` 则可以承接归因结果，沉淀成可优化的问题：
+
+```text
+root_cause_category:
+  planning_error
+
+is_skill_attributable:
+  true
+
+SkillIssue:
+  当前 skill 缺少测试验证步骤，导致 agent 修改后没有确认结果。
+```
+
+所以根因归因 evaluator 可以把“评测分低”转成“可以进入建议模块的问题候选”。
+
+### 推荐优先级
+
+这个指标值得加入预置评估器，但不建议第一版做得太重。
+
+推荐 MVP：
+
+```text
+RootCauseAttributionEvaluator
+```
+
+第一版只做：
+
+- 输入：task、trace、final_output、已有 evaluator 分数。
+- 输出：`root_cause_category`、`critical_steps`、`evidence`、`confidence`、`suggested_fix`。
+- 支持固定 taxonomy。
+- 对成功样本输出 `n_a`。
+- 对低置信度样本输出 `unknown`，并提示可进入 AgentDebug。
+
+暂时不要第一版就做：
+
+- 完整 DAG 因果传播。
+- 多根因概率图。
+- 长篇自然语言诊断。
+- 自动改 skill。
+- 替代 AgentDebug。
+
+### 参考链接
+
+- [OpenAI Agent evals](https://developers.openai.com/api/docs/guides/agent-evals)：提供 agent workflow / trace 评估思路和 grader 基础设施，适合实现自定义根因归因 grader。
+- [OpenAI graders](https://developers.openai.com/api/docs/guides/graders)：说明如何用结构化 grader 对模型或 agent 输出进行自动评估。
+- [LangSmith evaluation concepts](https://docs.langchain.com/langsmith/evaluation-concepts)：提供 dataset、experiment、custom evaluator、trace/run tree 等评估基础设施。
+- [AgentEval: Towards Holistic Evaluation of LLM Agents](https://arxiv.org/abs/2604.23581)：提出将 agent execution 建成带依赖关系的 DAG，并用 typed metrics / failure taxonomy 支持更细粒度的失败分析。
+- [TRACE: A Comprehensive Benchmark for Continual Learning in Large Language Model Agents](https://arxiv.org/abs/2510.02837)：体现了从任务轨迹和持续任务表现分析 agent 行为退化与失败的 benchmark 思路。
+- [AgentDebug 诊断原理与循环检测补强](../docs/agentdebug-diagnosis-principle-and-loop-detection-gap.md)：项目内对 AgentDebug “逐 step 认知错误检测 + 单点根因定位”以及轨迹级循环检测的说明。
+- [Agent Insight 智能诊断用户指南](../docs/user-guide/observability/diagnosis.md)：项目内对智能诊断页面、Trace/Span 证据、模块级归因和 AgentDebug 定位的说明。
+
+## Q10：如果想参考 Phoenix Tool Selection 的工具选择正确性，但需要对整条 trace 一次性评测，落地建议是什么？
+
+### 简短结论
+
+不要把整条 trace 原样塞进一个 Phoenix Tool Selection prompt 里，让 judge 一次性给一个“工具选择正确 / 不正确”的结论。
+
+更推荐的落地方式是：
+
+```text
+把 Phoenix Tool Selection 当成“单个工具决策点”的判断逻辑；
+在 Agent Insight 里额外做一个 trace-level orchestrator，
+先从整条 trace 里抽取所有工具选择决策点，
+再把多个决策点打包给一次 judge 批量评估，
+最后聚合成整条 trace 的工具选择正确性分数。
+```
+
+也就是：
+
+```text
+Phoenix 原始思路：
+  input + available_tools + tool_selection -> correct / incorrect
+
+Agent Insight trace 级实现：
+  trace -> tool decision points[]
+        -> batched Tool Selection judge
+        -> trace-level aggregate score + findings
+```
+
+这样既保留 Phoenix Tool Selection 的核心逻辑，又避免“一个工具决策点一次 LLM 调用”的成本问题。
+
+### Phoenix Tool Selection 原始边界
+
+Phoenix Tool Selection 的目标是判断：
+
+```text
+LLM 是否为当前任务选择了最合适的工具。
+```
+
+它关注的是工具选择的 “what”，不是工具参数是否正确。参数正确性应该交给 Tool Invocation。
+
+Phoenix 文档里要求的核心输入是：
+
+| 输入 | 含义 |
+| --- | --- |
+| `input` | 当前对话上下文或用户问题 |
+| `available_tools` / `availableTools` | 可用工具列表及描述 |
+| `tool_selection` / `toolSelection` | LLM 实际选择的工具 |
+
+输出通常是：
+
+```text
+label: correct / incorrect
+score: 1.0 / 0.0
+explanation: 判断理由
+```
+
+它支持的评估层级主要是 span 级，尤其适合包含 tool calls 的 LLM span。参考：[Phoenix Tool Selection](https://arize.com/docs/phoenix/evaluation/pre-built-metrics/tool-selection)。
+
+所以如果要评整条 trace，需要你们在 Phoenix 思路外面加一层“trace 级抽取和聚合”。
+
+### 为什么不能只评实际发生的 tool call？
+
+一个常见误区是：
+
+```text
+只找出 trace 里所有 tool call，
+逐个判断“这个工具选得对不对”。
+```
+
+这样能发现：
+
+- 选错工具。
+- 选了不存在的工具。
+- 多工具任务只选了部分工具。
+- 选了不相关工具。
+
+但它发现不了一个很重要的问题：
+
+```text
+本来应该调用工具，但 agent 没有调用。
+```
+
+例如：
+
+```text
+用户要求“读取这个文件并总结”
+agent 没有读文件，直接凭空回答。
+```
+
+trace 里没有 tool call，如果只评实际 tool call，这条 trace 反而没有任何可评点。
+
+所以 trace 级 Tool Selection 必须同时评两类决策：
+
+```text
+1. actual tool decision:
+   agent 实际选择了某个工具，判断选得对不对。
+
+2. missing tool decision:
+   agent 没有选择工具，但当时其实应该选择工具。
+```
+
+这也是整条 trace 级评估比 Phoenix 原始 span 级评估多出来的关键复杂度。
+
+### 推荐整体架构
+
+建议做成一个新的预置评估器：
+
+```text
+TraceToolSelectionEvaluator
+```
+
+内部由四步组成：
+
+```text
+1. Trace 解析
+2. 工具决策点抽取
+3. 批量 Tool Selection 评估
+4. Trace 级聚合
+```
+
+流程图：
+
+```text
+Trace
+  -> normalize spans / turns
+  -> extract decision points
+  -> build one batched Phoenix-style eval input
+  -> judge all decision points in one call
+  -> aggregate score
+  -> output trace-level result + findings
+```
+
+### 第一步：Trace 解析
+
+先把原始 trace 规范化成统一结构：
+
+```json
+{
+  "trace_id": "trace_123",
+  "task": "用户原始任务",
+  "steps": [
+    {
+      "step_index": 1,
+      "span_id": "span_1",
+      "kind": "llm",
+      "input_messages": [],
+      "output_text": "...",
+      "tool_calls": [],
+      "available_tools": []
+    },
+    {
+      "step_index": 2,
+      "span_id": "span_2",
+      "kind": "tool",
+      "tool_name": "read_file",
+      "tool_args": {},
+      "tool_result": "..."
+    }
+  ]
+}
+```
+
+这里要注意：`available_tools` 应该尽量取“当时这个 agent 实际可用的工具”，而不是系统全局所有工具。
+
+因为在多 agent / 多 skill 场景里，不同节点可用工具可能不同：
+
+```text
+root agent 可用工具 != subagent 可用工具
+某个 skill 加载后可用工具 != 加载前可用工具
+沙箱权限变化前后可用工具也可能不同
+```
+
+如果只能拿到全局工具列表，评估仍可运行，但置信度应该降低。
+
+### 第二步：抽取工具决策点
+
+工具决策点不是所有 span，而是 agent 在某一刻“选择是否使用工具、使用哪个工具”的位置。
+
+建议抽取四类：
+
+#### 1. 有 tool calls 的 LLM span
+
+这是最直接的情况：
+
+```text
+LLM span output 里包含 tool_calls
+```
+
+每个工具调用都可以形成一个决策点，多个工具调用也可以合并成一个 multi-tool decision。
+
+```json
+{
+  "decision_id": "d1",
+  "type": "actual_tool_selection",
+  "step_index": 3,
+  "selected_tools": ["read_file"],
+  "decision_context": "用户要求读取 README 并总结，agent 当前准备读取文件"
+}
+```
+
+#### 2. 该用工具但没有用的 LLM span
+
+这是 trace 级评估必须补上的能力。
+
+候选场景：
+
+- 用户请求读取、搜索、运行、修改、查询外部状态。
+- agent 直接最终回答，但没有任何对应工具调用。
+- agent 声称已经完成某个外部动作，但 trace 里没有工具证据。
+- 当前上下文缺少必要信息，但 agent 没有检索或读取。
+
+例如：
+
+```json
+{
+  "decision_id": "d2",
+  "type": "no_tool_selected",
+  "step_index": 5,
+  "selected_tools": [],
+  "decision_context": "用户要求检查测试是否通过，但 agent 直接回答测试通过，没有运行测试工具"
+}
+```
+
+这类点需要 LLM judge 或规则 + LLM 混合判断。不要用太激进的规则，否则会把正常的纯推理回答误判成漏用工具。
+
+#### 3. 多工具任务中的不完整选择
+
+有些任务天然需要多个工具或多个阶段：
+
+```text
+读取文件 -> 修改文件 -> 运行测试
+搜索资料 -> 打开来源 -> 汇总引用
+查询订单 -> 修改订单 -> 确认结果
+```
+
+如果 agent 只做了其中一步，单个 tool call 可能看起来是正确的，但整条 trace 仍然工具选择不完整。
+
+所以需要在 trace 级识别：
+
+```text
+selected_tools 是不是覆盖了完成任务所需的关键工具集合？
+```
+
+这可以作为一个单独的 finding：
+
+```text
+missing_required_tool_sequence
+```
+
+#### 4. 不该用工具却用了工具
+
+有些任务只需要直接回答，调用工具反而是错误：
+
+```text
+用户问一个概念解释，agent 却调用文件写入工具。
+用户只要求总结已给文本，agent 却外部搜索。
+```
+
+Phoenix Tool Selection 原本也覆盖 “selected a tool when none was needed”。trace 级实现需要把这种情况保留下来。
+
+标签可以是：
+
+```text
+unnecessary_tool_use
+```
+
+### 第三步：构造批量 Phoenix-style 输入
+
+不要对每个决策点单独调用 judge，而是把多个工具决策点压缩成一个数组，一次性评估。
+
+批量输入可以长这样：
+
+```json
+{
+  "task": "用户原始任务",
+  "available_tools": "read_file: Read a file...\nrun_tests: Run test command...",
+  "decisions": [
+    {
+      "decision_id": "d1",
+      "step_index": 3,
+      "span_id": "span_3",
+      "type": "actual_tool_selection",
+      "context_before_decision": "用户要求总结 README，agent 当前需要获取 README 内容。",
+      "selected_tools": ["read_file"]
+    },
+    {
+      "decision_id": "d2",
+      "step_index": 8,
+      "span_id": "span_8",
+      "type": "no_tool_selected",
+      "context_before_decision": "agent 修改代码后准备最终回复，但 trace 中没有测试验证工具调用。",
+      "selected_tools": []
+    }
+  ]
+}
+```
+
+这个结构仍然继承 Phoenix Tool Selection 的三件事：
+
+```text
+input:
+  用户任务 + 当前决策点上下文
+
+available_tools:
+  当时可用工具列表
+
+tool_selection:
+  当前决策点实际选择的工具
+```
+
+区别只是：原来一次 judge 评一个 `tool_selection`，现在一次 judge 评一个 `decisions[]`。
+
+关键是不要把完整 trace 原文直接塞进去，而是为每个 decision 生成短上下文。
+
+更好的格式是：
+
+```text
+User task:
+  ...
+
+Available tools:
+  ...
+
+Tool decisions to evaluate:
+  d1:
+    context before decision: ...
+    selected tools: ...
+
+  d2:
+    context before decision: ...
+    selected tools: No tools called
+```
+
+这样 judge 看到的是“多个压缩后的工具选择决策”，而不是一大坨原始日志。
+
+如果决策点是“没有工具调用”，`tool_selection` 可以写：
+
+```text
+No tools called
+```
+
+这和 Phoenix 文档里的建议一致。
+
+### 第四步：批量评估逻辑
+
+批量 judge 可以沿用 Phoenix 的判断标准，但要求它返回数组化结果。
+
+Phoenix 原始是：
+
+```text
+correct / incorrect
+```
+
+trace 级实现建议用：
+
+```text
+correct
+partial
+incorrect
+n_a
+```
+
+原因是整条 trace 里经常出现“工具方向对，但不完整”的情况。
+
+例如：
+
+```text
+用户要求修改代码并跑测试。
+agent 选择 edit_file。
+```
+
+单看“修改代码”阶段，`edit_file` 是对的；但从完整任务看，还缺少测试验证。这里用 `partial` 比直接 `incorrect` 更有解释力。
+
+批量 judge 的输出可以是：
+
+```json
+{
+  "decision_results": [
+    {
+      "decision_id": "d1",
+      "step_index": 3,
+      "span_id": "span_3",
+      "label": "correct",
+      "score": 1.0,
+      "selected_tools": ["read_file"],
+      "expected_tools": ["read_file"],
+      "error_type": null,
+      "severity": "none",
+      "explanation": "read_file is the appropriate tool because the task requires reading README content.",
+      "confidence": 0.86
+    },
+    {
+      "decision_id": "d2",
+      "step_index": 8,
+      "span_id": "span_8",
+      "label": "incorrect",
+      "score": 0.0,
+      "selected_tools": [],
+      "expected_tools": ["run_tests"],
+      "error_type": "missing_required_tool",
+      "severity": "medium",
+      "explanation": "The agent claimed completion after code changes without selecting a test or verification tool.",
+      "confidence": 0.78
+    }
+  ]
+}
+```
+
+这种方式的好处是：
+
+- LLM 调用次数从 N 次变成 1 次。
+- judge 可以在同一个任务上下文里比较多个工具选择，减少局部误判。
+- 输出仍然保留 `decision_id`，所以可以回写到具体 span / step。
+- trace 级聚合可以直接消费 `decision_results[]`。
+
+需要控制的是输入长度。如果一条 trace 有非常多工具决策点，可以限制只送关键决策点，或者按固定窗口分批，例如每批 10-20 个 decision。即便分批，也比逐点调用便宜很多。
+
+### 第五步：Trace 级聚合
+
+不要只简单平均。工具选择错误对最终结果的影响不一样。
+
+建议同时提供三个分数：
+
+| 分数 | 含义 |
+| --- | --- |
+| `tool_selection_average_score` | 所有有效决策点的平均分 |
+| `critical_tool_selection_score` | 关键决策点是否正确，错一个关键点会明显降分 |
+| `trace_tool_selection_pass` | 严格通过：关键工具选择都正确，且没有高严重度错误 |
+
+推荐聚合规则：
+
+```text
+decision_score:
+  correct = 1.0
+  partial = 0.5
+  incorrect = 0.0
+  n_a = excluded
+
+weight:
+  critical decision = 2.0
+  normal decision = 1.0
+  low-impact decision = 0.5
+
+trace_score:
+  weighted average over valid decisions
+
+hard fail:
+  hallucinated tool
+  missing required tool that blocks task completion
+  unsafe / forbidden tool
+  wrong tool causing irreversible action
+```
+
+示例：
+
+```json
+{
+  "trace_score": 0.72,
+  "trace_label": "partial",
+  "decision_count": 5,
+  "incorrect_decision_count": 1,
+  "partial_decision_count": 2,
+  "critical_failure": false,
+  "findings": [
+    {
+      "type": "missing_required_tool",
+      "severity": "medium",
+      "step_index": 8,
+      "expected_tools": ["run_tests"],
+      "selected_tools": [],
+      "evidence": "agent claimed the fix was complete without running tests"
+    }
+  ]
+}
+```
+
+### 推荐输出 schema
+
+建议 trace 级 evaluator 输出：
+
+```json
+{
+  "evaluator": "TraceToolSelectionEvaluator",
+  "score": 0.72,
+  "label": "partial",
+  "direction": "maximize",
+  "summary": "Most tool choices were appropriate, but the agent skipped test verification before finalizing.",
+  "decision_count": 5,
+  "valid_decision_count": 4,
+  "decision_results": [
+    {
+      "decision_id": "d1",
+      "step_index": 3,
+      "span_id": "span_3",
+      "label": "correct",
+      "score": 1.0,
+      "selected_tools": ["read_file"],
+      "expected_tools": ["read_file"],
+      "error_type": null,
+      "severity": "none",
+      "confidence": 0.86
+    }
+  ],
+  "findings": [
+    {
+      "type": "missing_required_tool",
+      "severity": "medium",
+      "step_index": 8,
+      "span_id": "span_8",
+      "selected_tools": [],
+      "expected_tools": ["run_tests"],
+      "evidence": "The final answer claimed success, but no test tool was called.",
+      "suggested_fix": "Require test verification before reporting code changes as complete."
+    }
+  ],
+  "metadata": {
+    "aggregation": "weighted_average_with_critical_failure_penalty",
+    "available_tools_source": "span",
+    "judge_model": "..."
+  }
+}
+```
+
+### 错误类型建议
+
+为了后续统计，建议固定错误类型：
+
+| 错误类型 | 含义 |
+| --- | --- |
+| `wrong_tool` | 选择了不适合当前任务的工具 |
+| `hallucinated_tool` | 选择了不存在或不可用工具 |
+| `missing_required_tool` | 需要工具但没有调用 |
+| `unnecessary_tool_use` | 不需要工具却调用 |
+| `incomplete_tool_set` | 多工具任务只选了部分工具 |
+| `wrong_tool_order` | 工具选择顺序错误 |
+| `unsafe_tool_choice` | 选择了危险或违反约束的工具 |
+| `redundant_tool_choice` | 选择了重复、无收益的工具 |
+| `n_a` | 当前点不适合评工具选择 |
+
+注意：`wrong_tool_order` 介于工具选择和过程评估之间。第一版可以先只标记，不强行纳入分数，避免评估器过重。
+
+### 实现上建议分两种模式
+
+#### 模式 A：Annotation 模式
+
+把每个工具决策点的评分写回对应 span：
+
+```text
+span annotation:
+  tool_selection_score
+  tool_selection_label
+  tool_selection_error_type
+```
+
+优点：
+
+- 方便在 trace 页面定位问题。
+- 和 Phoenix span-level 思路一致。
+- 用户能看到每个节点为什么被扣分。
+
+#### 模式 B：Trace Aggregate 模式
+
+把整条 trace 的聚合结果写成一个 trace-level evaluation：
+
+```text
+trace evaluation:
+  trace_tool_selection_score
+  trace_tool_selection_label
+  summary
+  findings
+```
+
+优点：
+
+- 适合评测中心排序、筛选、对比。
+- 能和任务完成度、轨迹效率、计划质量等指标一起看。
+
+推荐两个模式都做：
+
+```text
+span annotation 用于解释；
+trace aggregate 用于报表。
+```
+
+### 第一版 MVP 怎么做
+
+第一版不需要做得太复杂。建议范围：
+
+```text
+MVP:
+  1. 只抽取 LLM span 的 tool_calls 和 final-answer no-tool decision。
+  2. 把所有 decision 打包成一次 Phoenix-style batched prompt。
+  3. judge 返回 decision_results[]，每个 decision 给 correct / partial / incorrect。
+  4. 聚合成 trace_score。
+  5. 输出 findings。
+```
+
+先不做：
+
+- 完整 workflow DAG。
+- 自动推导所有“应该调用但没调用”的隐藏决策点。
+- 复杂工具顺序评分。
+- 跨 agent 工具权限变化的完美建模。
+- 和 Tool Invocation / Tool Response Handling 的联合归因。
+
+第一版可接受的限制是：
+
+```text
+能发现大部分 wrong tool、hallucinated tool、unnecessary tool、明显 missing tool；
+对隐含的漏调用工具保持保守，低置信度时不强判。
+```
+
+### 和其他工具指标怎么配合？
+
+trace 级 Tool Selection 只回答：
+
+```text
+工具选得对不对？
+```
+
+它不回答：
+
+```text
+工具参数对不对？
+工具结果有没有读懂？
+工具调用顺序是否最高效？
+最终任务有没有完成？
+```
+
+建议组合：
+
+| 指标 | 回答 |
+| --- | --- |
+| Trace Tool Selection | 是否选了正确工具 |
+| Tool Invocation | 参数、格式、调用是否正确 |
+| Tool Response Handling | 是否正确理解和使用工具结果 |
+| Step Efficiency | 是否有冗余、绕路、无效重复 |
+| Task Completion | 最终任务是否完成 |
+| Root Cause Attribution | 如果失败，主要失败源在哪里 |
+
+一个典型诊断链是：
+
+```text
+Task Completion 低
+  -> Trace Tool Selection 低
+  -> wrong_tool / missing_required_tool
+  -> Root Cause Attribution 归因为 action/tool_selection_error
+```
+
+### 最推荐的落地形态
+
+最终建议：
+
+```text
+不要直接复刻 Phoenix Tool Selection 为 trace 级大 prompt。
+要实现一个 Agent Insight 自己的 TraceToolSelectionEvaluator。
+```
+
+它的核心设计是：
+
+```text
+1. Phoenix-style 工具选择判断逻辑
+2. Agent Insight trace 决策点抽取
+3. batched judge 一次评多个 decision
+4. weighted aggregation
+5. span annotation + trace evaluation 双输出
+```
+
+这样能同时满足：
+
+- 和业界 Phoenix 指标对齐。
+- 适配你们自己的 trace 数据结构。
+- 能捕获“该用工具但没用”的整条 trace 问题。
+- 能在评测中心形成可比较分数。
+- 能在 trace 页面定位具体失败步骤。