agent-insight 0.5.0 → 0.5.2

package/.next/standalone/Evaluation_and_Research/agent_evaluator_research_qna_3.md

@@ -0,0 +1,712 @@
+# Agent 评估器调研问答 3
+
+调研日期：2026-07-07
+
+这份文档用于继续记录 `agent_evaluator_industry_research.md` 里的细节问题。上一份问答见 `agent_evaluator_research_qna_2.md`。
+
+## Q8：多 Agent 交接 / 路由正确性的逻辑是什么？
+
+### 简短结论
+
+多 Agent 交接 / 路由正确性评估的是：
+
+```text
+在多 agent 系统里，主 agent 是否在正确时机，把正确任务，用正确上下文，交给正确的子 agent；
+子 agent 完成后，主 agent 是否正确接收、整合和继续推进。
+```
+
+它不是单纯看“有没有调用子 agent”，而是看整个 handoff / routing 链路是否合理。
+
+可以拆成四段：
+
+```text
+1. 是否应该交接
+2. 交给谁
+3. 交接内容是否完整
+4. 交接后结果是否被正确使用
+```
+
+### 为什么这个指标重要？
+
+多 agent 系统的失败经常不是某个 agent 单独能力差，而是协作链路出了问题：
+
+- 主 agent 不该派发时派发了。
+- 该派发时没有派发。
+- 派给了错误角色。
+- 子 agent 收到的上下文不完整。
+- 子 agent 做完了，但父 agent 没有使用结果。
+- 多个子 agent 重复做同一件事。
+- 子 agent 的结论互相冲突，父 agent 没有裁决。
+
+这类问题用普通任务完成度很难定位。最终失败只会显示“没完成”，但真正原因可能是：
+
+```text
+路由错了，后面全都偏了。
+```
+
+所以这个指标的意义是把多 agent 失败定位到“协作/编排层”，而不是误归因到工具、最终答案或某个子 agent 的能力。
+
+### 输入是什么？
+
+一个多 agent 路由评估器通常需要完整 trace 或 agent tree，至少包含：
+
+```text
+user_task:
+  用户原始任务
+
+available_agents:
+  可用 agent / subagent 列表、职责说明、能力边界
+
+handoff_events:
+  父 agent 何时派发、派给谁、派发参数/任务说明
+
+subagent_traces:
+  子 agent 实际执行过程和输出
+
+parent_followup:
+  父 agent 如何使用子 agent 结果，是否继续推进/整合/验证
+
+final_output:
+  最终回复或最终状态
+```
+
+如果没有可用 agent 的职责说明，就很难判断“派给谁是否正确”。这时 evaluator 只能根据 agent 名称和 trace 内容做弱判断，置信度应降低。
+
+### 中间评估逻辑
+
+#### 1. 判断是否需要交接
+
+先看用户任务是否真的需要子 agent。
+
+适合交接的情况：
+
+- 任务可以自然拆成多个专业子任务。
+- 需要某个专门 agent 的能力，例如 researcher、coder、reviewer、diagnoser。
+- 主 agent 的职责不覆盖该动作。
+- 并行处理能明显降低复杂度。
+- 需要独立验证或复核。
+
+不适合交接的情况：
+
+- 单步简单任务。
+- 子 agent 和主 agent 能力重复。
+- 派发成本高于收益。
+- 派发会丢失上下文或权限。
+
+可能的判断标签：
+
+```text
+handoff_needed
+handoff_unnecessary
+handoff_missing
+```
+
+#### 2. 判断路由目标是否正确
+
+如果确实发生了 handoff，要判断交给的子 agent 是否匹配任务。
+
+例如：
+
+```text
+任务：分析日志中的 Kerberos 错误
+正确路由：diagnosis / log-analysis agent
+错误路由：frontend-ui agent
+```
+
+判断依据：
+
+- 子 agent 的职责说明。
+- 子任务内容。
+- 子 agent 实际执行行为。
+- 子 agent 是否具备需要的工具/skill。
+
+常见错误：
+
+```text
+wrong_agent_type
+over_broad_agent
+missing_specialist
+duplicated_routing
+```
+
+#### 3. 判断交接内容是否完整
+
+路由目标正确还不够，handoff payload 也必须完整。
+
+交接内容通常应包含：
+
+- 用户原始目标。
+- 当前已知上下文。
+- 已完成步骤。
+- 待解决子任务。
+- 约束和边界。
+- 可用证据或文件路径。
+- 期望输出格式。
+- 禁止事项或风险提示。
+
+错误例子：
+
+```text
+父 agent 让子 agent “看一下这个问题”，
+但没有给日志路径、用户目标、前面已经试过的命令。
+```
+
+这会导致子 agent 重复探索、做错范围或输出不可用结果。
+
+可能的标签：
+
+```text
+context_complete
+missing_user_goal
+missing_evidence
+missing_constraints
+missing_expected_output
+ambiguous_task
+```
+
+#### 4. 判断子 agent 是否完成被交接任务
+
+子 agent 收到任务后，需要看它是否完成了自己的子目标。
+
+这里不是评估整体任务完成度，而是评估：
+
+```text
+这个 handoff 所定义的子任务有没有完成？
+```
+
+例如：
+
+```text
+父 agent 派 researcher 查资料
+=> 子 agent 是否真的找到了相关资料并给出可用摘要？
+
+父 agent 派 reviewer 检查代码
+=> 子 agent 是否真的指出问题或确认无问题？
+```
+
+这一步可以使用局部 task completion / tool correctness / evidence quality。
+
+#### 5. 判断父 agent 是否正确接收和整合结果
+
+很多多 agent 问题发生在“子 agent 做完以后”。
+
+父 agent 应该：
+
+- 读取子 agent 输出。
+- 判断是否可信。
+- 处理冲突结论。
+- 把子 agent 结果整合进最终答案。
+- 必要时继续追问或补充验证。
+
+常见错误：
+
+```text
+subagent_result_ignored:
+  子 agent 给了关键结论，父 agent 没用。
+
+subagent_result_misread:
+  父 agent 误解了子 agent 输出。
+
+conflict_not_resolved:
+  多个子 agent 结论冲突，父 agent 直接拼接。
+
+no_parent_synthesis:
+  父 agent 直接转发子 agent 输出，没有完成最终整合。
+```
+
+#### 6. 判断整体依赖关系是否合理
+
+复杂多 agent workflow 不是一条线，而是 DAG：
+
+```text
+root
+  -> researcher
+  -> coder
+      -> test-runner
+  -> reviewer
+```
+
+评估要看：
+
+- coder 是否依赖 researcher 的结果。
+- reviewer 是否在 coder 之后执行。
+- test-runner 是否在修改之后执行。
+- 父 agent 是否等待必要子任务完成。
+
+这和 AgentEval 的 DAG 思路一致：把 agent execution 看成带依赖的步骤图，而不是扁平步骤列表。依赖建模能帮助定位上游哪一步导致后续失败。
+
+### 输出应该是什么？
+
+一个多 agent 路由评估器可以输出：
+
+```json
+{
+  "score": 0.72,
+  "label": "partial",
+  "handoff_needed": true,
+  "routing_correctness": 0.8,
+  "handoff_context_quality": 0.6,
+  "subagent_task_completion": 0.9,
+  "parent_integration_quality": 0.5,
+  "findings": [
+    {
+      "type": "missing_context",
+      "severity": "medium",
+      "parent_agent": "root",
+      "child_agent": "researcher",
+      "handoff_step": 4,
+      "evidence": "handoff payload omitted the user's expected output format",
+      "impact": "child output was useful but hard for parent to integrate"
+    }
+  ]
+}
+```
+
+建议至少保留这些字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `score` | 0-1 总分 |
+| `label` | correct / partial / incorrect / n_a |
+| `handoff_needed` | 是否应该交接 |
+| `routing_correctness` | 是否交给正确 agent |
+| `handoff_context_quality` | 交接上下文是否完整 |
+| `subagent_task_completion` | 子 agent 是否完成子任务 |
+| `parent_integration_quality` | 父 agent 是否正确使用结果 |
+| `findings` | 具体问题列表 |
+| `evidence_steps` | 对应 trace step / span |
+
+### 常见失败模式
+
+#### 1. 该交接但没交接
+
+```text
+任务需要专业诊断 agent，但 root agent 自己硬做，导致漏掉关键检查。
+```
+
+标签：
+
+```text
+missing_handoff
+```
+
+#### 2. 不该交接却交接
+
+```text
+简单问题派给多个子 agent，造成成本高、延迟高、答案不一致。
+```
+
+标签：
+
+```text
+unnecessary_handoff
+```
+
+#### 3. 交给错误 agent
+
+```text
+需要数据库 agent，却派给文档总结 agent。
+```
+
+标签：
+
+```text
+wrong_agent
+```
+
+#### 4. 交接上下文缺失
+
+```text
+父 agent 没传用户目标、文件路径、已知事实、失败历史。
+```
+
+标签：
+
+```text
+incomplete_handoff_context
+```
+
+#### 5. 子 agent 做对了但父 agent 没用
+
+```text
+子 agent 找到了根因，父 agent 最终答案没有引用或采纳。
+```
+
+标签：
+
+```text
+ignored_subagent_result
+```
+
+#### 6. 子 agent 输出冲突未解决
+
+```text
+两个子 agent 给出不同结论，父 agent 没有裁决或验证。
+```
+
+标签：
+
+```text
+unresolved_subagent_conflict
+```
+
+#### 7. 父子职责边界混乱
+
+```text
+父 agent 交给子 agent 后自己又重复执行同一任务；
+或者子 agent 越权执行本应由父 agent 决策的最终动作。
+```
+
+标签：
+
+```text
+role_boundary_violation
+```
+
+### 它和工具选择评估有什么区别？
+
+两者很像，但对象不同。
+
+| 指标 | 路由对象 | 关注点 |
+| --- | --- | --- |
+| Tool Selection | 工具 | 是否选择了正确工具 |
+| Multi-Agent Routing | 子 agent / handoff | 是否选择了正确执行角色，并正确交接上下文 |
+
+工具调用通常是：
+
+```text
+function(args) -> result
+```
+
+多 agent 交接是：
+
+```text
+delegate(task + context + constraints) -> subagent work + result
+```
+
+所以多 agent 路由比工具选择多了几个问题：
+
+- 子任务定义是否清楚。
+- 上下文是否完整。
+- 子 agent 是否真的完成子任务。
+- 父 agent 是否整合结果。
+- 多个子 agent 的依赖是否正确。
+
+### 它和任务完成度有什么关系？
+
+任务完成度回答：
+
+```text
+最后有没有完成用户目标？
+```
+
+多 agent 路由正确性回答：
+
+```text
+多 agent 协作过程是否正确？
+```
+
+典型组合：
+
+| 任务完成度 | 路由正确性 | 说明 |
+| --- | --- | --- |
+| 高 | 高 | 多 agent 协作健康 |
+| 高 | 低 | 可能偶然成功；有成本、稳定性或可维护性风险 |
+| 低 | 高 | 路由没问题，失败可能在工具、环境、子 agent 能力 |
+| 低 | 低 | 协作编排本身就是主要问题 |
+
+### 适用场景
+
+这个指标适合：
+
+- 多 agent 编排系统。
+- 有 root agent / subagent 结构的 Coding Agent。
+- 复杂诊断 agent。
+- 自动化运维 agent。
+- 研究-写作-审核分工类 agent。
+- 工作流 agent，例如 planner -> executor -> reviewer。
+- 需要 handoff 的客服或业务办理 agent。
+
+不适合：
+
+- 单 agent 系统。
+- 没有子 agent / handoff 的 trace。
+- 只有普通工具调用、没有角色分工的任务。
+
+这些场景应该标记：
+
+```text
+n_a: no multi-agent handoff
+```
+
+### 在 Agent Insight 里可以怎么理解
+
+Agent Insight 已经有 root / sub-agent execution tree，这类指标天然可以利用：
+
+```text
+parentExecutionId
+rootExecutionId
+agentSessionId
+subagentType
+subagentName
+isSubagent
+```
+
+评估时可以从 trace 中抽：
+
+```text
+handoff step:
+  父 agent 何时调用 task/subagent
+
+handoff payload:
+  subagent_type、任务说明、上下文、load_skills
+
+child execution:
+  子 agent 的执行 trace、工具调用、最终输出
+
+parent continuation:
+  父 agent 是否读取并使用子 agent 输出
+```
+
+这样可以把问题定位到：
+
+```text
+父 agent 路由错
+子 agent 执行错
+交接上下文错
+父 agent 整合错
+```
+
+这比只看整体 trace 分更有行动价值。
+
+### 附加问题：业界有代码参考吗，还是只有方法论？
+
+简短结论：
+
+```text
+目前更多是方法论 + 平台能力 + 自定义 evaluator 模式，
+还没有特别成熟、通用、开箱即用的“多 Agent 交接 / 路由正确性”标准代码库。
+```
+
+和工具调用不同，工具调用已经有比较清晰的结构：
+
+```text
+tool_name
+arguments
+tool_result
+```
+
+所以 Phoenix / Ragas / DeepEval 可以做出比较通用的 Tool Selection、Tool Invocation、Tool Call Accuracy。
+
+但多 agent handoff 的结构差异很大：
+
+```text
+有的系统叫 handoff
+有的系统叫 task / delegate / subagent
+有的是 LangGraph node transition
+有的是 swarm/router
+有的是 supervisor-worker
+有的是 planner-executor-reviewer
+```
+
+每个系统里的“正确交接”都依赖：
+
+- 子 agent 职责定义。
+- workflow 拓扑。
+- 任务类型。
+- handoff payload 结构。
+- 父 agent 是否需要整合。
+- 是否允许并行或重规划。
+
+所以业界更多提供的是 **可实现这个 evaluator 的框架能力**，而不是一个通用 evaluator 函数。
+
+#### 1. OpenAI agent evals：有 trace grading 能力，但需要自定义 rubric
+
+[OpenAI agent evals](https://developers.openai.com/api/docs/guides/agent-evals) 的价值在于：它支持对 agent workflow / trace 做评估，也可以用 grader 问类似：
+
+```text
+是否发生了正确 handoff？
+是否违反了指令？
+是否调用了正确工具？
+```
+
+但它不是提供一个固定的 `MultiAgentHandoffCorrectnessMetric()`。
+
+更接近的用法是：
+
+```text
+你自己定义 grader rubric
+把 trace / spans / handoff events 放进去
+让 grader 输出 pass/fail、score、reason
+```
+
+所以 OpenAI 提供的是 eval infrastructure 和 grader 机制，不是一个 handoff correctness 的现成指标实现。
+
+#### 2. LangSmith：有 trace / dataset / evaluator 基础设施，但 handoff 评估通常自定义
+
+[LangSmith](https://docs.langchain.com/langsmith/evaluation-concepts) 很适合做这类评估，因为它有：
+
+- trace / run tree。
+- dataset。
+- custom evaluator。
+- experiment comparison。
+- human annotation。
+
+如果你的多 agent 系统在 LangGraph / LangChain 里跑，LangSmith 能看到 intermediate steps / child runs / tool calls。
+
+但同样地，它通常不会替你定义“什么叫正确 handoff”。你需要写自定义 evaluator：
+
+```text
+读取 run tree
+抽取 supervisor -> worker 的转移
+对照 agent role description / expected route
+判断路由和上下文是否正确
+```
+
+所以 LangSmith 是很好的实现平台，但不是通用现成 metric。
+
+#### 3. AgentEval：非常接近方法论，但更像论文框架
+
+[AgentEval](https://arxiv.org/abs/2604.23581) 是目前比较接近“多步骤 / 多 agent / 工作流评估”的方法论参考。
+
+它的核心思路是：
+
+```text
+把 agent execution 建模成 DAG
+每个节点有 typed quality metrics
+节点之间有依赖关系
+通过 failure taxonomy 和 dependency propagation 做根因定位
+```
+
+这对多 agent handoff 很有启发，因为 handoff 本质上就是 DAG 里的边：
+
+```text
+parent node -> child agent node
+```
+
+可以评估：
+
+- 这条边是否应该存在。
+- 边指向的节点是否正确。
+- 边上传递的上下文是否完整。
+- 下游节点失败是否由上游交接错误导致。
+
+但从公开资料看，AgentEval 更主要是论文和方法框架；它给了很强的设计参考，不等于可以直接 npm install / pip install 后得到一个通用 handoff evaluator。
+
+#### 4. 其他多 agent benchmark：多评“协作结果”，少评“交接正确性”
+
+一些 multi-agent benchmark 会评估协作能力，例如：
+
+- BattleAgentBench：多 agent 合作/竞争能力。
+- COMMA：多模态多 agent 沟通协作。
+- 一些 domain workflow benchmark：多步骤、多场景任务成功率。
+
+它们通常更关注：
+
+```text
+多 agent 协作后任务是否完成？
+协作表现是否好？
+```
+
+但不一定细到：
+
+```text
+第 3 步是否应该 handoff？
+handoff payload 是否缺少用户约束？
+父 agent 是否正确整合子 agent 输出？
+```
+
+所以这些 benchmark 可以借鉴任务设计和数据集形态，但不能直接当作 handoff correctness evaluator。
+
+### 可以参考的代码形态是什么？
+
+虽然没有通用标准代码，但可以参考三类实现形态。
+
+#### 1. Run tree / trace parser
+
+先把多 agent trace 解析成结构化树：
+
+```json
+{
+  "agent": "root",
+  "events": [...],
+  "children": [
+    {
+      "agent": "researcher",
+      "handoff_step": 4,
+      "handoff_payload": {...},
+      "events": [...],
+      "result": "..."
+    }
+  ]
+}
+```
+
+Agent Insight 现有 `buildAgentCallTree` / root-subagent execution 模型就属于这一层。
+
+#### 2. Handoff extractor
+
+从 tree 中抽取 handoff record：
+
+```json
+{
+  "parent_agent": "root",
+  "child_agent": "researcher",
+  "handoff_step": 4,
+  "handoff_reason": "need external research",
+  "payload": {
+    "task": "...",
+    "context": "...",
+    "constraints": "..."
+  },
+  "child_result": "...",
+  "parent_used_result": true
+}
+```
+
+#### 3. LLM judge / rule hybrid evaluator
+
+用规则先做确定性检查：
+
+```text
+是否真的有 child execution
+是否有 child result
+父 agent 后续是否引用 child result
+handoff payload 是否为空
+是否重复派发同一子任务
+```
+
+再用 LLM judge 判断语义：
+
+```text
+是否应该派发？
+派给这个 agent 是否合理？
+上下文是否足够？
+父 agent 是否正确整合？
+```
+
+### 对 Agent Insight 的判断
+
+如果我们要做这个预置评估器，不能简单“集成某个现成库”。更现实的路线是：
+
+```text
+借鉴 OpenAI / LangSmith 的 trace grading 模式
+借鉴 AgentEval 的 DAG / dependency / root cause 方法论
+复用 Agent Insight 自己的 root-subagent trace tree
+实现一个自定义 Multi-Agent Routing Evaluator
+```
+
+也就是说：
+
+```text
+业界有可参考的评估思想和平台能力；
+但具体到多 agent handoff correctness，最好由 Agent Insight 自己实现。
+```
+
+这反而是 Agent Insight 的机会，因为你们已经有多 agent execution tree、parent/root execution 关系、subagentName/subagentType 等数据，能做得比通用平台更贴近真实 trace。
+
+### 参考链接
+
+- OpenAI agent evals: https://developers.openai.com/api/docs/guides/agent-evals
+- AgentEval DAG step-level evaluation: https://arxiv.org/abs/2604.23581
+- LangSmith evaluation concepts: https://docs.langchain.com/langsmith/evaluation-concepts