Skip to content

The agent engineering platform.

fix(langchain): prevent orphaned `tool_calls` in `ToolCallLimitMiddleware` end behavior (#39258)

Nishitha M8f7cee0b52bd
diff --git a/libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py b/libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py
index 1dfc5e4e6e..620b7bc7b1 100644
--- a/libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py
+++ b/libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py
@@ -26,9 +26,10 @@ ExitBehavior = Literal["continue", "error", "end"]
- `'continue'`: Block exceeded tools with error messages, let other tools continue
(default)
- `'error'`: Raise a `ToolCallLimitExceededError` exception
-- `'end'`: Stop execution immediately, injecting a `ToolMessage` and an `AIMessage` for
- the single tool call that exceeded the limit. Raises `NotImplementedError` if there
- are other pending tool calls (due to parallel tool calling).
+- `'end'`: Stop execution immediately, injecting a `ToolMessage` for each tool call
+ that exceeded the limit and an `AIMessage` explaining why. Any other pending tool
+ call on the same `AIMessage` (e.g. from parallel tool calling) also gets an
+ explanatory `ToolMessage` instead of being executed.
"""
@@ -148,9 +149,9 @@ class ToolCallLimitMiddleware(AgentMiddleware[ToolCallLimitState[ResponseT], Con
- `exit_behavior`: How to handle when limits are exceeded
- `'continue'`: Block exceeded tools, let execution continue (default)
- `'error'`: Raise an exception
- - `'end'`: Stop immediately with a `ToolMessage` + AI message for the single
- tool call that exceeded the limit (raises `NotImplementedError` if there
- are other pending tool calls (due to parallel tool calling).
+ - `'end'`: Stop immediately with a `ToolMessage` for each exceeded tool
+ call, a `ToolMessage` explaining any other pending calls were skipped,
+ and an AI message explaining why execution stopped
Examples:
!!! example "Continue execution with blocked tools (default)"
@@ -220,10 +221,11 @@ class ToolCallLimitMiddleware(AgentMiddleware[ToolCallLimitState[ResponseT], Con
- `'continue'`: Block exceeded tools with error messages, let other
tools continue. Model decides when to end.
- `'error'`: Raise a `ToolCallLimitExceededError` exception
- - `'end'`: Stop execution immediately with a `ToolMessage` + AI message
- for the single tool call that exceeded the limit. Raises
- `NotImplementedError` if there are multiple parallel tool
- calls to other tools or multiple pending tool calls.
+ - `'end'`: Stop execution immediately with a `ToolMessage` for each
+ tool call that exceeded the limit and an AI message explaining
+ why. Any other pending tool call on the same `AIMessage` (e.g.
+ from parallel tool calling) is given an explanatory
+ `ToolMessage` instead of being executed.
Raises:
ValueError: If both limits are `None`, if `exit_behavior` is invalid,
@@ -336,13 +338,12 @@ class ToolCallLimitMiddleware(AgentMiddleware[ToolCallLimitState[ResponseT], Con
Returns:
State updates with incremented tool call counts. If limits are exceeded
and exit_behavior is `'end'`, also includes a jump to end with a
- `ToolMessage` and AI message for the single exceeded tool call.
+ `ToolMessage` for each exceeded tool call, an explanatory
+ `ToolMessage` for any other pending tool calls, and an AI message.
Raises:
ToolCallLimitExceededError: If limits are exceeded and `exit_behavior`
is `'error'`.
- NotImplementedError: If limits are exceeded, `exit_behavior` is `'end'`,
- and there are multiple tool calls.
"""
# Get the last AIMessage to check for tool calls
messages = state.get("messages", [])
@@ -419,20 +420,24 @@ class ToolCallLimitMiddleware(AgentMiddleware[ToolCallLimitState[ResponseT], Con
]
if self.exit_behavior == "end":
- # Check if there are tool calls to other tools that would continue executing
- other_tools = [
- tc
- for tc in last_ai_message.tool_calls
- if self.tool_name is not None and tc["name"] != self.tool_name
+ # Since jumping to `"end"` skips tool execution, add `ToolMessage`s for all
+ # pending calls so none are executed and the message history stays valid.
+ blocked_ids = {tool_call["id"] for tool_call in blocked_calls}
+ pending_tool_calls = [
+ tc for tc in last_ai_message.tool_calls if tc["id"] not in blocked_ids
]
-
- if other_tools:
- tool_names = ", ".join({tc["name"] for tc in other_tools})
- msg = (
- f"Cannot end execution with other tool calls pending. "
- f"Found calls to: {tool_names}. Use 'continue' or 'error' behavior instead."
+ artificial_messages.extend(
+ ToolMessage(
+ content=(
+ "Execution stopped before this tool call could run because "
+ "another tool call in the same batch exceeded the limit."
+ ),
+ tool_call_id=tool_call["id"],
+ name=tool_call.get("name"),
+ status="error",
)
- raise NotImplementedError(msg)
+ for tool_call in pending_tool_calls
+ )
# Build final AI message content (displayed to user - includes thread/run details)
# Use hypothetical thread count (what it would have been if call wasn't blocked)
@@ -447,6 +452,10 @@ class ToolCallLimitMiddleware(AgentMiddleware[ToolCallLimitState[ResponseT], Con
)
artificial_messages.append(AIMessage(content=final_msg_content))
+ # Since no calls execute after jumping to `"end"`, don't include this batch in
+ # the thread-level count. Only the run-level count tracks attempted calls.
+ thread_counts[count_key] = current_thread_count
+
return {
"thread_tool_call_count": thread_counts,
"run_tool_call_count": run_counts,
@@ -476,12 +485,11 @@ class ToolCallLimitMiddleware(AgentMiddleware[ToolCallLimitState[ResponseT], Con
Returns:
State updates with incremented tool call counts. If limits are exceeded
and exit_behavior is `'end'`, also includes a jump to end with a
- `ToolMessage` and AI message for the single exceeded tool call.
+ `ToolMessage` for each exceeded tool call, an explanatory
+ `ToolMessage` for any other pending tool calls, and an AI message.
Raises:
ToolCallLimitExceededError: If limits are exceeded and `exit_behavior`
is `'error'`.
- NotImplementedError: If limits are exceeded, `exit_behavior` is `'end'`,
- and there are multiple tool calls.
"""
return self.after_model(state, runtime)
diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_call_limit.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_call_limit.py
index 9050eb6751..d5207a6ce5 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_call_limit.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/implementations/test_tool_call_limit.py
@@ -163,12 +163,10 @@ def test_middleware_unit_functionality() -> None:
def test_middleware_end_behavior_with_unrelated_parallel_tool_calls() -> None:
"""Test middleware 'end' behavior with unrelated parallel tool calls.
- Test that 'end' behavior raises NotImplementedError when there are parallel calls
- to unrelated tools.
-
- When limiting a specific tool with "end" behavior and the model proposes parallel calls
- to BOTH the limited tool AND other tools, we can't handle this scenario (we'd be stopping
- execution while other tools should run).
+ When limiting a specific tool with "end" behavior and the model proposes parallel
+ calls to BOTH the limited tool AND other tools, execution still stops immediately,
+ but the unrelated call gets an explanatory `ToolMessage` instead of being executed,
+ so it isn't left orphaned in the message history.
"""
# Limit search tool specifically
middleware = ToolCallLimitMiddleware(tool_name="search", thread_limit=1, exit_behavior="end")
@@ -189,10 +187,22 @@ def test_middleware_end_behavior_with_unrelated_parallel_tool_calls() -> None:
run_tool_call_count={"search": 1},
)
- with pytest.raises(
- NotImplementedError, match="Cannot end execution with other tool calls pending"
- ):
- middleware.after_model(state, runtime) # type: ignore[arg-type]
+ result = middleware.after_model(state, runtime) # type: ignore[arg-type]
+ assert result is not None
+ assert result["jump_to"] == "end"
+
+ tool_messages = [msg for msg in result["messages"] if isinstance(msg, ToolMessage)]
+ assert len(tool_messages) == 2, "Both the exceeded call and the unrelated call get a message"
+
+ search_msg = next(msg for msg in tool_messages if msg.tool_call_id == "1")
+ calculator_msg = next(msg for msg in tool_messages if msg.tool_call_id == "2")
+ assert search_msg.status == "error"
+ assert "Tool call limit exceeded" in search_msg.content
+ assert calculator_msg.status == "error"
+ assert "exceeded the limit" in calculator_msg.content
+ assert result["thread_tool_call_count"] == {"search": 1}, (
+ "Thread count shouldn't advance since the blocked call never executed"
+ )
def test_middleware_with_specific_tool() -> None:
@@ -686,71 +696,95 @@ def test_parallel_tool_calls_with_limit_continue_mode() -> None:
def test_parallel_tool_calls_with_limit_end_mode() -> None:
"""Test parallel tool calls with a limit of 1 in 'end' mode.
- When the model proposes 3 tool calls with a limit of 1:
- - The first call would be allowed (within limit)
- - The 2nd and 3rd calls exceed the limit and get blocked with error ToolMessages
- - Execution stops immediately (jump_to: end) so NO tools actually execute
- - An AI message explains why execution stopped
+ When the model proposes 3 tool calls with a limit of 1, the first call would be
+ allowed (within limit) while the 2nd and 3rd exceed it. Jumping to "end" skips the
+ tool-execution node entirely, so `ToolCallLimitMiddleware` gives the allowed call
+ an explanatory `ToolMessage` too (instead of executing it, or leaving it
+ "orphaned" with no response at all).
"""
+ middleware = ToolCallLimitMiddleware(thread_limit=1, exit_behavior="end")
+ runtime = None
- @tool
- def search(query: str) -> str:
- """Search for information."""
- return f"Results: {query}"
-
- # Model proposes 3 parallel search calls
- model = FakeToolCallingModel(
- tool_calls=[
- [
- ToolCall(name="search", args={"query": "q1"}, id="1"),
- ToolCall(name="search", args={"query": "q2"}, id="2"),
- ToolCall(name="search", args={"query": "q3"}, id="3"),
- ],
- [],
- ]
+ state = ToolCallLimitState(
+ messages=[
+ AIMessage(
+ "Response",
+ tool_calls=[
+ {"name": "search", "args": {"query": "q1"}, "id": "1"},
+ {"name": "search", "args": {"query": "q2"}, "id": "2"},
+ {"name": "search", "args": {"query": "q3"}, "id": "3"},
+ ],
+ ),
+ ],
+ thread_tool_call_count={},
+ run_tool_call_count={},
)
- limiter = ToolCallLimitMiddleware(thread_limit=1, exit_behavior="end")
- agent = create_agent(
- model=model, tools=[search], middleware=[limiter], checkpointer=InMemorySaver()
- )
+ result = middleware.after_model(state, runtime) # type: ignore[arg-type]
+ assert result is not None
+ assert result["jump_to"] == "end"
- result = agent.invoke(
- {"messages": [HumanMessage("Test")]}, {"configurable": {"thread_id": "test"}}
+ tool_messages = [msg for msg in result["messages"] if isinstance(msg, ToolMessage)]
+ assert len(tool_messages) == 3, "Every tool call gets a matching ToolMessage"
+ assert {msg.tool_call_id for msg in tool_messages} == {"1", "2", "3"}
+ assert all(msg.status == "error" for msg in tool_messages)
+
+ exceeded_msgs = [msg for msg in tool_messages if msg.tool_call_id in {"2", "3"}]
+ allowed_msg = next(msg for msg in tool_messages if msg.tool_call_id == "1")
+ assert all("Tool call limit exceeded" in msg.content for msg in exceeded_msgs)
+ assert "exceeded the limit" in allowed_msg.content
+
+ # None of the 3 calls actually ran (jump_to="end" skips the tool node), including
+ # call "1" which `_separate_tool_calls` classified as "allowed" — so the thread
+ # count must stay at its pre-batch value, not be incremented for that call.
+ assert result["thread_tool_call_count"] == {"__all__": 0}, (
+ "Thread count shouldn't advance for calls that never actually executed"
)
- messages = result["messages"]
- # Verify tool message counts
- # With "end" behavior, when we jump to end, NO tools execute (not even allowed ones)
- # We only get error ToolMessages for the 2 blocked calls
- tool_messages = [msg for msg in messages if isinstance(msg, ToolMessage)]
- successful_tool_messages = [msg for msg in tool_messages if msg.status != "error"]
- error_tool_messages = [msg for msg in tool_messages if msg.status == "error"]
- assert len(successful_tool_messages) == 0, "No tools execute when we jump to end"
- assert len(error_tool_messages) == 2, "Should have 2 blocked tool messages (q2, q3)"
+def test_middleware_end_behavior_with_allowed_and_blocked_parallel_calls() -> None:
+ """Regression test for orphaned tool_calls when tool_name is unset (langchain#34159).
- # Verify error tool messages (sent to model - include "Do not" instruction)
- for error_msg in error_tool_messages:
- assert "Tool call limit exceeded" in error_msg.content
- assert "Do not" in error_msg.content
+ When `exit_behavior="end"` and the middleware limits all tools (`tool_name=None`),
+ a single `AIMessage` with parallel tool calls can have some calls allowed (under
+ the limit) and some blocked (over the limit). Previously, only the blocked call
+ got a `ToolMessage`, so the allowed call was left without a matching response — an
+ invalid message history that raises a 400 error on the next turn. The allowed call
+ must now get an explanatory `ToolMessage` too.
+ """
+ middleware = ToolCallLimitMiddleware(run_limit=2, exit_behavior="end")
+ runtime = None
- # Verify AI message explaining why execution stopped
- # (displayed to user - includes thread/run details)
- ai_limit_messages = []
- for msg in messages:
- if not isinstance(msg, AIMessage):
- continue
- assert isinstance(msg.content, str)
- if "limit" in msg.content.lower() and not msg.tool_calls:
- ai_limit_messages.append(msg)
- assert len(ai_limit_messages) == 1, "Should have exactly one AI message explaining the limit"
+ state = ToolCallLimitState(
+ messages=[
+ AIMessage(
+ "Response",
+ tool_calls=[
+ {"name": "get_summarized_eda_data", "args": {}, "id": "call_1"},
+ {"name": "get_org_psych_analysis", "args": {}, "id": "call_2"},
+ ],
+ ),
+ ],
+ thread_tool_call_count={"__all__": 1},
+ run_tool_call_count={"__all__": 1},
+ )
- ai_msg_content = ai_limit_messages[0].content
- assert isinstance(ai_msg_content, str)
- assert "thread limit exceeded" in ai_msg_content.lower() or (
- "run limit exceeded" in ai_msg_content.lower()
- ), "AI message should include thread/run limit details for the user"
+ result = middleware.after_model(state, runtime) # type: ignore[arg-type]
+ assert result is not None
+ assert result["jump_to"] == "end"
+
+ tool_messages = [msg for msg in result["messages"] if isinstance(msg, ToolMessage)]
+ assert {msg.tool_call_id for msg in tool_messages} == {"call_1", "call_2"}, (
+ "Every tool call on the AIMessage must get a matching ToolMessage"
+ )
+ assert all(msg.status == "error" for msg in tool_messages)
+
+ # `call_1` was "allowed" by `_separate_tool_calls`, but it never actually
+ # executes once we jump to "end", so it must not permanently consume the
+ # thread's quota — the count should stay at its pre-batch value (1).
+ assert result["thread_tool_call_count"] == {"__all__": 1}, (
+ "Thread count shouldn't advance for a call that never actually executed"
+ )
def test_parallel_mixed_tool_calls_with_specific_tool_limit() -> None: