从零了解 Langfuse 6:Agent 与 Tool 调用观测
内容核验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

相关新闻

让 AI 重构旧代码,怎样把“行为不变”变成可检查的要求?

让 AI 重构旧代码,怎样把“行为不变”变成可检查的要求?

“行为不变”,要先说清楚哪些行为 旧代码功能正常,只是函数太长、命名难懂、重复判断越来越多。这时让 AI 帮忙整理,很容易得到一份看起来更漂亮的代码。但代码变短了、分支变少了,并不能说明重构成功。 真正需要验收的是&#…

2026/11/19 10:27:13 阅读更多 →
基于Python与face_recognition的人脸识别考勤系统:从摄像头到SQLite完整实现

基于Python与face_recognition的人脸识别考勤系统:从摄像头到SQLite完整实现

简介:面向计算机相关专业毕业设计与课程设计需求,这份基于深度学习的人脸识别考勤系统源码,提供了人脸检测、特征提取、打卡记录等完整流程。项目经导师指导并通过评审,得分98分,适合正在做大作业、期末项目或毕设开发…

2026/11/15 22:29:32 阅读更多 →
手作复现困境:用记录系统把创作流程变成可复用资产

手作复现困境:用记录系统把创作流程变成可复用资产

最近在整理一个叫 artcraft 的个人创作项目,核心就一句话:把“艺术设计”和“手工制作”这两段本来经常脱节的流程,拧成一条可以复用的流水线。以前我做热缩片挂件、小木牌、桌面摆件,基本是兴致来了就动手,做完往柜子…

2026/11/19 4:31:11 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/18 13:59:04 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/18 15:33:23 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/18 17:05:28 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/18 14:33:19 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/18 17:05:28 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/18 14:13:08 阅读更多 →

日新闻

周新闻

月新闻