langfuse Coordinator 决策评测规范

目录

• Coordinator 决策评测
  • Langfuse Trace Contract v1.0
  • 一、层级与生命周期规范（必须遵守）
    • 1️⃣ Trace（一次测试用例 / 用户请求）
    • 2️⃣ Chain（一个 Agent 的完整决策）
    • 3️⃣ Span（可选）
  • 二、Input Contract（评测 Ground Truth）
    • ✅ 必须字段（Mandatory）
    • 说明
    • ❌ 禁止行为
  • 三、Output Contract（模型预测结果）
    • ✅ 必须字段
    • 约束规则（非常重要）
  • 四、错误与降级 Contract
    • 推荐格式
  • 五、Langfuse 更新规则（硬性）
    • ✅ 允许
    • ❌ 禁止
  • 六、评测脚本 Contract（你后面 CI 会用）
  • 七、你现在代码要对齐的最小清单
  • 八、架构级一句话（很重要）
    • 下一步我可以继续帮你做的两件事（都很值钱）：

很好，这一步非常关键。我直接给你一份可以落地、可以作为团队规范的 Langfuse Trace Contract（Coordinator 决策评测版），不是概念稿，是你可以照着执行、review、CI 校验的那种。

---

Coordinator 决策评测

Langfuse Trace Contract v1.0

适用对象：Coordinator / Orchestrator / Routing Agent
目标：可评测、可回放、可回归

---

一、层级与生命周期规范（必须遵守）

1️⃣ Trace（一次测试用例 / 用户请求）

• 唯一标识：test_id
• 生命周期：一条 dataset 样本 = 一个 trace
• 职责：承载评测上下文

⚠️ 不允许一个 trace 对应多个 test_id

---

2️⃣ Chain（一个 Agent 的完整决策）

• Coordinator = 1 个 chain
• Orchestrator = 1 个 chain
• WorkflowAgent = 1 个 chain

@observe(name="coordinator_process", as_type="chain")

chain 的 input / output 是评测的核心对象

---

3️⃣ Span（可选）

• 仅用于：

  • intent parsing
  • rule routing
  • fallback

• 禁止在 span 层做评测判断

---

二、Input Contract（评测 Ground Truth）

input = 决策上下文 + 评测真值

✅ 必须字段（Mandatory）

{
  "test_id": "string",

  "user_message": "string",
  "messages": [ ... ],

  "expected_intent": ["INTENT_TYPE"],
  "expected_action": ["ACTION_TYPE"],
  "expected_agent": ["AGENT_NAME"]
}

说明

字段	说明
test_id	dataset 唯一键，评测 join key
expected_*	Ground Truth，仅用于评测

---

❌ 禁止行为

• ❌ 不得在 output 写 expected_*
• ❌ 不得缺失 test_id
• ❌ 不得把 expected 和 predicted 混在一起

---

三、Output Contract（模型预测结果）

output = Agent 的决策结果

✅ 必须字段

{
  "intents": [
    {
      "type": "INTENT_TYPE",
      "action": "ACTION_TYPE",
      "confidence": 0.0,
      "entities": { }
    }
  ],
  "route_to": "AGENT_NAME"
}

约束规则（非常重要）

1. intents 必须是数组（即使只有 1 个）

2. 每个 intent 必须包含 action

3. 多意图时：

   • len(intents) > 1
   • route_to == "orchestrator"

---

四、错误与降级 Contract

推荐格式

{
  "error": {
    "type": "PARSE_ERROR | LLM_ERROR | ROUTING_ERROR",
    "message": "string"
  },
  "route_to": "handoff"
}

错误也要可评测、可统计

---

五、Langfuse 更新规则（硬性）

✅ 允许

_safe_update_observation(input_data={...})
_safe_update_observation(output_data={...})

❌ 禁止

行为	原因
手动 flush	破坏生命周期
在 span 中写 expected	评测语义混乱
partial output	评测脚本难写

---

六、评测脚本 Contract（你后面 CI 会用）

评测脚本只依赖以下字段：

trace.input.test_id
trace.input.expected_*
trace.output.intents
trace.output.route_to

这保证了你可以：

• 换 prompt
• 换模型
• 换 LangGraph
• 不改评测逻辑

---

七、你现在代码要对齐的最小清单

你可以直接对照自检：

• test_id 注入 input
• expected_* 只在 input
• intents / route_to 只在 output
• 不手动 flush
• Coordinator 用 chain
• span 只做辅助，不做评测

---

八、架构级一句话（很重要）

Trace Contract 一旦定死，你的 Agent 系统就进入“可持续演进状态”。
没有它，评测永远是临时脚本。

你现在已经完成了 Agent 平台化的关键一步。

---

下一步我可以继续帮你做的两件事（都很值钱）：

1. 把这个 Contract 转成 Pydantic Schema + 自动校验
2. 设计一套 CI Evaluation Runner（失败样本自动回放）

你想下一步把哪一件也“定死”？