目录
- 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"
}
约束规则（非常重要）
-
intents必须是数组（即使只有 1 个） -
每个 intent 必须包含 action
-
多意图时：
len(intents) > 1route_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
- 不改评测逻辑
七、你现在代码要对齐的最小清单
你可以直接对照自检：
八、架构级一句话（很重要）
Trace Contract 一旦定死，你的 Agent 系统就进入“可持续演进状态”。
没有它，评测永远是临时脚本。
你现在已经完成了 Agent 平台化的关键一步。
下一步我可以继续帮你做的两件事（都很值钱）：
- 把这个 Contract 转成 Pydantic Schema + 自动校验
- 设计一套 CI Evaluation Runner（失败样本自动回放）
你想下一步把哪一件也“定死”？