The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
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.pyindex 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 stoppedExamples:!!! 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 othertools 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], ConReturns:State updates with incremented tool call counts. If limits are exceededand 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 callsmessages = 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], ConReturns:State updates with incremented tool call counts. If limits are exceededand 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.pyindex 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 specificallymiddleware = 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: