feat(langgraph): extract original tool_call_id from runtime for consistency

Add _extract_tool_call_id function to handle MCP tool runtime objects and
prioritize original tool_call_id over run_id for consistent event tracking.
Update converter to use extracted ID or fallback to run_id when not available.
Add comprehensive tests for tool start/end events with runtime tool_call_id.

fixes inconsistent tool call ID tracking when using MCP tools that inject
runtime objects with original LLM-generated tool_call_id

为 runtime 对象添加提取原始 tool_call_id 的功能以确保一致性

添加 _extract_tool_call_id 函数来处理 MCP 工具 runtime 对象，并优先使用原始
tool_call_id 而不是 run_id 来确保事件跟踪的一致性。更新转换器以使用提取的 ID，
当不可用时回退到 run_id。为带有 runtime tool_call_id 的工具开始/结束事件添加
全面的测试。

修复使用注入包含原始 LLM 生成 tool_call_id 的 runtime 对象的 MCP 工具时
工具调用 ID 跟踪不一致的问题

Change-Id: I2838c7b88ea8c01c87b39038d2b92a06bea89167
Signed-off-by: OhYee <oyohyee@oyohyee.com>

Author: OhYee

agentrun/integration/langgraph/agent_converter.py

@@ -114,6 +114,31 @@ def _filter_tool_input(tool_input: Any) -> Any:
     return filtered
 
 
+def _extract_tool_call_id(tool_input: Any) -> Optional[str]:
+    """从工具输入中提取原始的 tool_call_id。
+
+    MCP 工具会在 input 中注入 runtime 对象，其中包含 LLM 返回的原始 tool_call_id。
+    使用这个 ID 可以保证工具调用事件的 ID 一致性。
+
+    Args:
+        tool_input: 工具输入（可能是 dict 或其他类型）
+
+    Returns:
+        tool_call_id 或 None
+    """
+    if not isinstance(tool_input, dict):
+        return None
+
+    # 尝试从 runtime 对象中提取 tool_call_id
+    runtime = tool_input.get("runtime")
+    if runtime is not None and hasattr(runtime, "tool_call_id"):
+        tc_id = runtime.tool_call_id
+        if isinstance(tc_id, str) and tc_id:
+            return tc_id
+
+    return None
+
+
 def _extract_content(chunk: Any) -> Optional[str]:
     """从 chunk 中提取文本内容"""
     if chunk is None:
@@ -538,13 +563,18 @@ def _convert_astream_events_event(
         run_id = event_dict.get("run_id", "")
         tool_name = event_dict.get("name", "")
         tool_input_raw = data.get("input", {})
+        # 优先使用 runtime 中的原始 tool_call_id，保证 ID 一致性
+        tool_call_id = _extract_tool_call_id(tool_input_raw) or run_id
         # 过滤掉内部字段（如 MCP 注入的 runtime）
         tool_input = _filter_tool_input(tool_input_raw)
 
-        if run_id:
+        if tool_call_id:
             yield AgentResult(
                 event=EventType.TOOL_CALL_START,
-                data={"tool_call_id": run_id, "tool_call_name": tool_name},
+                data={
+                    "tool_call_id": tool_call_id,
+                    "tool_call_name": tool_name,
+                },
             )
             if tool_input:
                 args_str = (
@@ -554,25 +584,28 @@ def _convert_astream_events_event(
                 )
                 yield AgentResult(
                     event=EventType.TOOL_CALL_ARGS,
-                    data={"tool_call_id": run_id, "delta": args_str},
+                    data={"tool_call_id": tool_call_id, "delta": args_str},
                 )
 
     # 4. 工具结束
     elif event_type == "on_tool_end":
         run_id = event_dict.get("run_id", "")
         output = data.get("output", "")
+        tool_input_raw = data.get("input", {})
+        # 优先使用 runtime 中的原始 tool_call_id，保证 ID 一致性
+        tool_call_id = _extract_tool_call_id(tool_input_raw) or run_id
 
-        if run_id:
+        if tool_call_id:
             yield AgentResult(
                 event=EventType.TOOL_CALL_RESULT,
                 data={
-                    "tool_call_id": run_id,
+                    "tool_call_id": tool_call_id,
                     "result": _format_tool_output(output),
                 },
             )
             yield AgentResult(
                 event=EventType.TOOL_CALL_END,
-                data={"tool_call_id": run_id},
+                data={"tool_call_id": tool_call_id},
             )
 
     # 5. LLM 结束

tests/unittests/integration/test_langchain_convert.py

@@ -307,6 +307,100 @@ def __str__(self):
         assert "internal" not in delta
         assert "__pregel" not in delta
 
+    def test_on_tool_start_uses_runtime_tool_call_id(self):
+        """测试 on_tool_start 使用 runtime 中的原始 tool_call_id 而非 run_id
+
+        MCP 工具会在 input.runtime 中注入 tool_call_id，这是 LLM 返回的原始 ID。
+        应该优先使用这个 ID，以保证工具调用事件的 ID 一致性。
+        """
+
+        class FakeToolRuntime:
+            """模拟 MCP 的 ToolRuntime 对象"""
+
+            def __init__(self, tool_call_id: str):
+                self.tool_call_id = tool_call_id
+
+        original_tool_call_id = "call_original_from_llm_12345"
+
+        event = {
+            "event": "on_tool_start",
+            "name": "get_weather",
+            "run_id": (
+                "run_id_different_from_tool_call_id"
+            ),  # run_id 与 tool_call_id 不同
+            "data": {
+                "input": {
+                    "city": "北京",
+                    "runtime": FakeToolRuntime(original_tool_call_id),
+                }
+            },
+        }
+
+        results = list(convert(event))
+
+        # TOOL_CALL_START + TOOL_CALL_ARGS
+        assert len(results) == 2
+
+        # 应该使用 runtime 中的原始 tool_call_id，而不是 run_id
+        assert results[0].event == EventType.TOOL_CALL_START
+        assert results[0].data["tool_call_id"] == original_tool_call_id
+        assert results[0].data["tool_call_name"] == "get_weather"
+
+        assert results[1].event == EventType.TOOL_CALL_ARGS
+        assert results[1].data["tool_call_id"] == original_tool_call_id
+
+    def test_on_tool_end_uses_runtime_tool_call_id(self):
+        """测试 on_tool_end 使用 runtime 中的原始 tool_call_id 而非 run_id"""
+
+        class FakeToolRuntime:
+            """模拟 MCP 的 ToolRuntime 对象"""
+
+            def __init__(self, tool_call_id: str):
+                self.tool_call_id = tool_call_id
+
+        original_tool_call_id = "call_original_from_llm_67890"
+
+        event = {
+            "event": "on_tool_end",
+            "run_id": "run_id_different_from_tool_call_id",
+            "data": {
+                "output": {"weather": "晴天", "temp": 25},
+                "input": {
+                    "city": "北京",
+                    "runtime": FakeToolRuntime(original_tool_call_id),
+                },
+            },
+        }
+
+        results = list(convert(event))
+
+        # TOOL_CALL_RESULT + TOOL_CALL_END
+        assert len(results) == 2
+
+        # 应该使用 runtime 中的原始 tool_call_id
+        assert results[0].event == EventType.TOOL_CALL_RESULT
+        assert results[0].data["tool_call_id"] == original_tool_call_id
+
+        assert results[1].event == EventType.TOOL_CALL_END
+        assert results[1].data["tool_call_id"] == original_tool_call_id
+
+    def test_on_tool_start_fallback_to_run_id(self):
+        """测试当 runtime 中没有 tool_call_id 时，回退使用 run_id"""
+        event = {
+            "event": "on_tool_start",
+            "name": "get_time",
+            "run_id": "run_789",
+            "data": {"input": {"timezone": "Asia/Shanghai"}},  # 没有 runtime
+        }
+
+        results = list(convert(event))
+
+        assert len(results) == 2
+        assert results[0].event == EventType.TOOL_CALL_START
+        # 应该回退使用 run_id
+        assert results[0].data["tool_call_id"] == "run_789"
+        assert results[1].data["tool_call_id"] == "run_789"
+
     def test_on_chain_stream_model_node(self):
         """测试 on_chain_stream 事件（model 节点）"""
         msg = create_mock_ai_message("你好！有什么可以帮你的吗？")