Skip to content

The agent engineering platform.

fix(core): add `tool_call_id` to `on_tool_error` event data (#33731)

Shreyansh Singh Gautam2ef23882d236
diff --git a/libs/core/langchain_core/runnables/schema.py b/libs/core/langchain_core/runnables/schema.py
index 919b7db410..29bbcd2cee 100644
--- a/libs/core/langchain_core/runnables/schema.py
+++ b/libs/core/langchain_core/runnables/schema.py
@@ -45,6 +45,12 @@ class EventData(TypedDict, total=False):
chunks support addition in general, and adding them up should result
in the output of the `Runnable` that generated the event.
"""
+ tool_call_id: NotRequired[str | None]
+ """The tool call ID associated with the tool execution.
+
+ This field is available for the `on_tool_error` event and can be used to
+ link errors to specific tool calls in stateless agent implementations.
+ """
class BaseStreamEvent(TypedDict):
diff --git a/libs/core/langchain_core/tools/base.py b/libs/core/langchain_core/tools/base.py
index 0b80fd27d7..e4c7cb3552 100644
--- a/libs/core/langchain_core/tools/base.py
+++ b/libs/core/langchain_core/tools/base.py
@@ -989,7 +989,7 @@ class ChildTool(BaseTool):
error_to_raise = e
if error_to_raise:
- run_manager.on_tool_error(error_to_raise)
+ run_manager.on_tool_error(error_to_raise, tool_call_id=tool_call_id)
raise error_to_raise
output = _format_output(content, artifact, tool_call_id, self.name, status)
run_manager.on_tool_end(output, color=color, name=self.name, **kwargs)
@@ -1119,7 +1119,7 @@ class ChildTool(BaseTool):
error_to_raise = e
if error_to_raise:
- await run_manager.on_tool_error(error_to_raise)
+ await run_manager.on_tool_error(error_to_raise, tool_call_id=tool_call_id)
raise error_to_raise
output = _format_output(content, artifact, tool_call_id, self.name, status)
diff --git a/libs/core/langchain_core/tracers/event_stream.py b/libs/core/langchain_core/tracers/event_stream.py
index f240026853..f4d16a83fb 100644
--- a/libs/core/langchain_core/tracers/event_stream.py
+++ b/libs/core/langchain_core/tracers/event_stream.py
@@ -73,6 +73,8 @@ class RunInfo(TypedDict):
"""The inputs to the run."""
parent_run_id: UUID | None
"""The ID of the parent run."""
+ tool_call_id: NotRequired[str | None]
+ """The tool call ID associated with the run."""
def _assign_name(name: str | None, serialized: dict[str, Any] | None) -> str:
@@ -301,6 +303,10 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
# vs. None value.
info["inputs"] = kwargs["inputs"]
+ if "tool_call_id" in kwargs:
+ # Store tool_call_id in run info for linking errors to tool calls
+ info["tool_call_id"] = kwargs["tool_call_id"]
+
self.run_map[run_id] = info
self.parent_map[run_id] = parent_run_id
@@ -663,6 +669,7 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
name_=name_,
run_type="tool",
inputs=inputs,
+ tool_call_id=kwargs.get("tool_call_id"),
)
self._send(
@@ -691,23 +698,27 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
**kwargs: Any,
) -> None:
"""Run when tool errors."""
+ # Extract tool_call_id from kwargs if passed directly, or from run_info
+ # (which was stored during on_tool_start) as a fallback
+ tool_call_id = kwargs.get("tool_call_id")
run_info, inputs = self._get_tool_run_info_with_inputs(run_id)
-
- self._send(
- {
- "event": "on_tool_error",
- "data": {
- "error": error,
- "input": inputs,
- },
- "run_id": str(run_id),
- "name": run_info["name"],
- "tags": run_info["tags"],
- "metadata": run_info["metadata"],
- "parent_ids": self._get_parent_ids(run_id),
+ if tool_call_id is None:
+ tool_call_id = run_info.get("tool_call_id")
+
+ event: StandardStreamEvent = {
+ "event": "on_tool_error",
+ "data": {
+ "error": error,
+ "input": inputs,
+ "tool_call_id": tool_call_id,
},
- "tool",
- )
+ "run_id": str(run_id),
+ "name": run_info["name"],
+ "tags": run_info["tags"],
+ "metadata": run_info["metadata"],
+ "parent_ids": self._get_parent_ids(run_id),
+ }
+ self._send(event, "tool")
@override
async def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
diff --git a/libs/core/tests/unit_tests/runnables/test_runnable_events_v2.py b/libs/core/tests/unit_tests/runnables/test_runnable_events_v2.py
index 4a99123a46..49342d2fc1 100644
--- a/libs/core/tests/unit_tests/runnables/test_runnable_events_v2.py
+++ b/libs/core/tests/unit_tests/runnables/test_runnable_events_v2.py
@@ -2837,3 +2837,74 @@ def test_default_is_v2() -> None:
"""Test that we default to version="v2"."""
signature = inspect.signature(Runnable.astream_events)
assert signature.parameters["version"].default == "v2"
+
+
+async def test_tool_error_event_includes_tool_call_id() -> None:
+ """Test that on_tool_error event includes tool_call_id when provided."""
+
+ @tool
+ def failing_tool(x: int) -> str: # noqa: ARG001
+ """A tool that always fails."""
+ msg = "Tool execution failed"
+ raise ValueError(msg)
+
+ tool_call_id = "test-tool-call-id-123"
+
+ # Invoke the tool with a tool call dict that includes the tool_call_id
+ tool_call = {
+ "name": "failing_tool",
+ "args": {"x": 42},
+ "id": tool_call_id,
+ "type": "tool_call",
+ }
+
+ events: list[StreamEvent] = []
+
+ # Need to use async for loop to collect events before exception is raised.
+ # List comprehension would fail entirely when exception occurs.
+ async def collect_events() -> None:
+ async for event in failing_tool.astream_events(tool_call, version="v2"):
+ events.append(event) # noqa: PERF401
+
+ with pytest.raises(ValueError, match="Tool execution failed"):
+ await collect_events()
+
+ # Find the on_tool_error event
+ error_events = [e for e in events if e["event"] == "on_tool_error"]
+ assert len(error_events) == 1
+
+ error_event = error_events[0]
+ assert error_event["name"] == "failing_tool"
+ assert "tool_call_id" in error_event["data"]
+ assert error_event["data"]["tool_call_id"] == tool_call_id
+
+
+async def test_tool_error_event_tool_call_id_is_none_when_not_provided() -> None:
+ """Test that on_tool_error event has tool_call_id=None when not provided."""
+
+ @tool
+ def failing_tool_no_id(x: int) -> str: # noqa: ARG001
+ """A tool that always fails."""
+ msg = "Tool execution failed"
+ raise ValueError(msg)
+
+ events: list[StreamEvent] = []
+
+ # Need to use async for loop to collect events before exception is raised.
+ # List comprehension would fail entirely when exception occurs.
+ async def collect_events() -> None:
+ async for event in failing_tool_no_id.astream_events({"x": 42}, version="v2"):
+ events.append(event) # noqa: PERF401
+
+ # Invoke the tool without a tool_call_id (regular dict input)
+ with pytest.raises(ValueError, match="Tool execution failed"):
+ await collect_events()
+
+ # Find the on_tool_error event
+ error_events = [e for e in events if e["event"] == "on_tool_error"]
+ assert len(error_events) == 1
+
+ error_event = error_events[0]
+ assert error_event["name"] == "failing_tool_no_id"
+ assert "tool_call_id" in error_event["data"]
+ assert error_event["data"]["tool_call_id"] is None