fix(core): add tool_call_id to on_tool_error event data

[Shreyansh Singh Gautam (Shreyanshsingh23)]

Add tool_call_id to on_tool_error event data

Summary

This PR addresses issue #33597 by adding tool_call_id to the on_tool_error callback event data. This enables users to link tool errors to specific tool calls in stateless agent implementations, which is essential for building OpenAI-compatible APIs and tracking tool execution flows.

Problem

When streaming events using astream_events with version="v2", the on_tool_error event only included the error and input data, but lacked the tool_call_id. This made it difficult to:

• Link errors to specific tool calls in stateless agent scenarios
• Implement OpenAI-compatible APIs that require tool call tracking
• Track tool execution flows when using run_id is not sufficient

Solution

The fix adds tool_call_id propagation through the callback chain:

1. Pass tool_call_id to callbacks: Updated BaseTool.run() and BaseTool.arun() to pass tool_call_id to both on_tool_start and on_tool_error callbacks
2. Store in event stream handler: Modified _AstreamEventsCallbackHandler to store tool_call_id in run info during on_tool_start
3. Include in error events: Updated on_tool_error handler to extract and include tool_call_id in the event data

Changes

• libs/core/langchain_core/tools/base.py:

  • Pass tool_call_id to on_tool_start in both sync and async methods
  • Pass tool_call_id to on_tool_error when errors occur

• libs/core/langchain_core/tracers/event_stream.py:

  • Store tool_call_id in run info during on_tool_start
  • Extract tool_call_id from kwargs or run info in on_tool_error
  • Include tool_call_id in the on_tool_error event data

Testing

The fix was verified by:

1. Direct tool invocation: Confirmed tool_call_id appears in on_tool_error event data when calling tools directly
2. Agent integration: Tested with create_agent to ensure tool_call_id is present in error events during agent execution

# Example verification
async for event in agent.astream_events(
    {"messages": "Please demonstrate a tool error"},
    version="v2",
):
    if event["event"] == "on_tool_error":
        assert "tool_call_id" in event["data"]  # ✓ Now passes
        print(event["data"]["tool_call_id"])

Backward Compatibility

• ✅ Fully backward compatible: tool_call_id is optional (can be None)
• ✅ No breaking changes: All changes are additive
• ✅ Existing code continues to work without modification

Related Issues

Fixes #33597

[codspeed-hq]

Merging this PR will improve performance by 15.54%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚡ 7 improved benchmarks
✅ 6 untouched benchmarks
⏩ 21 skipped benchmarks¹

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	WallTime	test_import_time[tool]	599.7 ms	519 ms	+15.54%
⚡	WallTime	test_import_time[CallbackManager]	541.2 ms	484.9 ms	+11.6%
⚡	WallTime	test_import_time[PydanticOutputParser]	594.1 ms	539.5 ms	+10.13%
⚡	WallTime	test_import_time[RunnableLambda]	544.7 ms	493.4 ms	+10.41%
⚡	WallTime	test_import_time[HumanMessage]	292.9 ms	258.5 ms	+13.32%
⚡	WallTime	test_import_time[InMemoryRateLimiter]	188.9 ms	171.5 ms	+10.18%
⚡	WallTime	test_import_time[Runnable]	568.7 ms	507.3 ms	+12.1%

---

_{Comparing Shreyanshsingh23:add-tool-call-id-to-on-tool-error (4f522b7) with master (e261924)}

Footnotes

1. 21 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[Shreyansh Singh Gautam (Shreyanshsingh23)]

Hey Eugene Yurtsev (@eyurtsev), should I go ahead and make changes in my code to solve this conflict or you are looking to do? Jusk asking before going ahead.

[j3r0lin]

Waiting for this feature

[日王 (chenzewang)]

on_tool_start and on_tool_end events also need tool_call_id

[Mason Daugherty (mdrxy)]

Shreyansh Singh Gautam (@Shreyanshsingh23) would you mind resolving the conflict?