内容核验2026-10-15参照当日 Langfuse 官方 v4 文档。本文以概念和设计示意为主不是完整可运行项目示例金额、分数、通过率和耗时均非实测数据。AgentScope/MCP 节点名称是业务埋点示例需要显式配置语义映射。版本和部署条件以文末官方资料为准。传统 LLM 应用是一问一答Agent 应用则会“自己决定下一步”。一旦加入 Tool、MCP、Retriever多步骤链路就会快速复杂化因此 Agent Observability 的重点是把决策与执行过程还原出来。本文基于 Langfuse 2026 年当前官方文档整理。Langfuse 迭代较快具体页面入口、字段名和版本要求请以官方最新文档为准。1. Agent 为什么比普通 LLM 更难观测普通聊天User → Model → AnswerAgentUser ↓ Agent ↓ Model ↓ Tool A ? Tool B ? Retriever ? ↓ Tool ↓ Model ↓ 另一个 Tool ↓ Model ↓ Answer问题会变成为什么调用这个 Tool 调用了几次 参数从哪里来 Tool Result 是否进入后续模型上下文 是否出现循环 哪个 Agent 子任务最慢2. Agent ObservationLangfuse 的 Observation Type 中包含agent。它适合表达一个 Agent 工作流 一个子 Agent 一个具备自主编排能力的步骤例如account-agent ├── planner-agent ├── MODEL_INFER ├── queryAccountBalance └── MODEL_INFERAgent Observation 的价值之一是帮助 Langfuse 识别 agentic workflow。3. Tool ObservationTool 调用建议使用tool类型。Tool 一般需要观察Tool Name Tool Input Tool Output Latency Status Error Metadata例如Tool: queryAccountBalance Input: { accountId: A001 } Output: { balance: 1000, currency: CNY }4. Tool Call 不等于 HTTP Call这是一个非常重要的设计点。例如TOOL_EXEC ↓ MCP Client ↓ MCP Server ↓ HTTP_OUTBOUND不要把它们全部压成HTTP 200 500ms因为 Tool 是业务语义HTTP 是技术实现。更合理Tool: queryAccountBalance │ ├── MCP_CALL └── HTTP_OUTBOUND这样既能看调用了哪个业务工具又能看具体网络调用哪里慢5. MCP 场景建议如何分层对于 MCP可以按Agent ↓ Tool ↓ MCP Client ↓ MCP Server ↓ Provider / HTTP来设计 Observation。示例AGENT_CALL agent │ ├── MODEL_INFER generation │ ├── TOOL_EXEC queryBalance tool │ │ │ ├── MCP_CLIENT_CALL span │ ├── MCP_SERVER_EXEC span │ └── HTTP_OUTBOUND span │ └── MODEL_INFER generation6. Tool Input 为什么特别重要Agent 很多问题并不是“Tool 选错”而是Tool 选对了但参数错了。例如Tool queryAccountBalance ✅ accountId 另一账户 ❌所以 Evaluation 后续可以拆成tool_selected_correct tool_args_correct这比一个总分更容易定位问题。7. Tool Output 为什么也要记录如果最终回答错误需要区分Tool Result 本身错误还是Tool Result 正确但模型理解错例如Tool Output: balance 1000 Final Answer: 余额为 10000显然 Tool 没问题问题发生在最后一次模型生成。8. Agent GraphLangfuse 可以把复杂 Agent Workflow 以 Graph 方式展示。当前官方说明中如果 Trace 包含 agentic Observation 类型Langfuse 可以根据 Observation 的嵌套和时间关系推导 Agent GraphLangGraph 集成也可以直接生成对应图形。这特别适合Multi-Agent 复杂 Tool 编排 循环调用 多分支 Agent相比树状 TraceGraph 更适合快速理解业务流程。9. 一个查询余额案例用户帮我查询账户余额理想链路UserAccount AgentModelqueryAccountBalanceMCP ServerBank APIModelFinal Answer对应观测Trace └── Agent ├── Generation #1 ├── Tool │ ├── MCP Span │ └── HTTP Span └── Generation #210. 怎么排查 Tool 选错建议顺序1. 看用户问题 2. 看 System Prompt 3. 看提供给模型的 Tool Schema / Description 4. 看 MODEL_INFER 的 Tool Call 5. 看实际 Tool Name 6. 看 Tool Args通常原因集中在Tool Description 不清晰 多个 Tool 描述重叠 Prompt 约束不足 模型能力问题 上下文中旧信息干扰11. 怎么排查 Tool 重复调用如果 Trace 出现Tool A Tool A Tool A Tool A要检查模型是否没有读懂 Tool Result Tool 返回是否缺少终止条件 Agent Loop 最大次数是否合理 错误是否被吞掉导致不停重试Trace 树通常比日志更容易发现这种模式。12. Agent 观测应该打哪些 Metadata可以考虑agentName agentVersion businessScene userId sessionId toolName mcpServer provider retryCount但不要无节制增加高基数字段否则后续聚合分析和存储成本都会受到影响。13. Tool 与 Evaluator 如何结合一旦 Tool 有结构化 Observation就可以做expectedTool actualTool进一步expected arguments actual arguments例如 Scoretool_correct true tool_args_correct false这会在第 10 篇 Evaluator 中进一步展开。14. AgentScope MCP 推荐结构如果已有REQUEST_ACCESS AGENT_CALL MODEL_INFER TOOL_EXEC HTTP_OUTBOUND建议继续保留这套业务语义而不是为了 Langfuse 全部改名。可以做语义映射AGENT_CALL → agent MODEL_INFER → generation TOOL_EXEC → tool HTTP_OUTBOUND → span这样既保留企业自己的观测规范又能让 Langfuse 正确理解 AI 语义。15. 生产环境注意事项Tool Input / Output 很容易包含账号 身份证明 业务报文 内部地址 客户数据因此必须考虑字段脱敏 黑白名单 长度截断 权限控制 数据保留周期Observability 的目标是提升可诊断性不是把所有原始敏感数据无限复制一份。16. 总结Agent Observability 的核心不是“多打几个 Span”而是把语义层级拆正确Agent → 谁在做决策 Generation → 模型怎么决策 Tool → 调了什么能力 MCP / HTTP → 能力如何真正执行当这四层关系清晰之后Agent Graph、Evaluator、Tool 正确率和回归测试才真正有价值。参考资料Langfuse /docs/observability/features/observation-typesLangfuse /docs/observability/features/agent-graphsLangfuse /docs/observability/data-model