bug: Langfuse trace show error on langgraph ToolNode with Command handoff

快速结论：该报错发生在通过 LangGraph 的 Command API 实现多智能体间交接（handoff）时。Langfuse 会将返回的 Command 对象识别为异常，导致跟踪记录显示错误标签。错误状态消息中只显示了 Command 对象的 JSON，没有实际错误信息。此问题已在最新版 Langfuse Python SDK 中修复（PR #1514）。

问题场景

用户在使用 langgraph 开发多智能体系统，基于 ToolNode 实现智能体间交接（handoff）功能。具体来说，tool 函数通过返回 Command(goto=agent_name, graph=Command.PARENT, update=...) 来导航到另一个智能体节点，并在 LangGraph 图执行过程中使用 LangfuseCallbackHandler 进行追踪。

报错原文

Langfuse trace shows error tag on the tool execution node of LangGraph.
Status message is the JSON value of the Command object. No detailed error message visible.

原因分析

LangGraph 内部的 ParentCommand 会经由 Command 对象传递到 Langfuse 追踪系统。Langfuse 在处理 Command 对象时，无法正确识别其正常执行状态，将其视为异常并标记为错误。根本原因是在 langgraph/graph/state.py（约第 993 行）中，ParentCommand 被抛出时与 Langfuse 的追踪逻辑存在兼容性问题。此问题已在 Langfuse Python SDK 的 PR #1514 中修复。

环境排查

确认 Langfuse Python SDK 版本：是否为 2.x 或更新版本（修复包含在 PR #1514 中）
确认 LangGraph 版本及关联依赖链中的 langchain-core 版本
确认 langgraph 主版本是否在 0.x 或 1.x 范围内，以便匹配对应的 SDK 修复

解决步骤

更新 Langfuse Python SDK 到最新版本。 该问题已在 langfuse-python 的 PR #1514 中修复，升级到包含该补丁的版本即可。
如果无法升级 SDK（例如受其他依赖约束），可优先尝试以下临时方案： 在自定义 handoff_to_agent 工具函数中，对 Command 返回结果进行封装，确保 langfuse 回调能够正确解析执行状态。例如，捕获 Command 对象并通过 langchain_core.tools 中的 ToolException 机制或手动设置 tool_call_id 状态标记。
验证配置： 检查 Langfuse 客户端初始化时是否正确配置了 trace_name 和 tags，确保回调链完整。

验证方法

升级 SDK 后，重新运行原有 graph 并观察 Langfuse 追踪页面：ToolNode 的跟踪节点不再显示红色”Error”标签，状态消息内容应为工具的正常返回文本（如 "Successfully transferred to agent_name"），而非 Command 对象的 JSON 表示。