Skip to content

The agent engineering platform.

feat(langchain_v1): Add ToolCallLimitMiddleware (#33269)

Nuno Campos2286d0d993a1
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 0000000000..7fca5eecae
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,10 @@
+{
+ "permissions": {
+ "allow": [
+ "Bash(uv run:*)",
+ "Bash(make:*)"
+ ],
+ "deny": [],
+ "ask": []
+ }
+}
\ No newline at end of file
diff --git a/libs/langchain_v1/langchain/agents/middleware/__init__.py b/libs/langchain_v1/langchain/agents/middleware/__init__.py
index 0222dba1f9..4c64d512a5 100644
--- a/libs/langchain_v1/langchain/agents/middleware/__init__.py
+++ b/libs/langchain_v1/langchain/agents/middleware/__init__.py
@@ -4,6 +4,7 @@ from .human_in_the_loop import HumanInTheLoopMiddleware
from .planning import PlanningMiddleware
from .prompt_caching import AnthropicPromptCachingMiddleware
from .summarization import SummarizationMiddleware
+from .tool_call_limit import ToolCallLimitMiddleware
from .types import (
AgentMiddleware,
AgentState,
@@ -24,6 +25,7 @@ __all__ = [
"ModelRequest",
"PlanningMiddleware",
"SummarizationMiddleware",
+ "ToolCallLimitMiddleware",
"after_model",
"before_model",
"dynamic_prompt",
diff --git a/libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py b/libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py
new file mode 100644
index 0000000000..f2abdaab09
--- /dev/null
+++ b/libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py
@@ -0,0 +1,260 @@
+"""Tool call limit middleware for agents."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from langchain_core.messages import AIMessage, AnyMessage, HumanMessage
+
+from langchain.agents.middleware.types import AgentMiddleware, AgentState, hook_config
+
+if TYPE_CHECKING:
+ from langgraph.runtime import Runtime
+
+
+def _count_tool_calls_in_messages(messages: list[AnyMessage], tool_name: str | None = None) -> int:
+ """Count tool calls in a list of messages.
+
+ Args:
+ messages: List of messages to count tool calls in.
+ tool_name: If specified, only count calls to this specific tool.
+ If None, count all tool calls.
+
+ Returns:
+ The total number of tool calls (optionally filtered by tool_name).
+ """
+ count = 0
+ for message in messages:
+ if isinstance(message, AIMessage) and message.tool_calls:
+ if tool_name is None:
+ # Count all tool calls
+ count += len(message.tool_calls)
+ else:
+ # Count only calls to the specified tool
+ count += sum(1 for tc in message.tool_calls if tc["name"] == tool_name)
+ return count
+
+
+def _get_run_messages(messages: list[AnyMessage]) -> list[AnyMessage]:
+ """Get messages from the current run (after the last HumanMessage).
+
+ Args:
+ messages: Full list of messages.
+
+ Returns:
+ Messages from the current run (after last HumanMessage).
+ """
+ # Find the last HumanMessage
+ last_human_index = -1
+ for i in range(len(messages) - 1, -1, -1):
+ if isinstance(messages[i], HumanMessage):
+ last_human_index = i
+ break
+
+ # If no HumanMessage found, return all messages
+ if last_human_index == -1:
+ return messages
+
+ # Return messages after the last HumanMessage
+ return messages[last_human_index + 1 :]
+
+
+def _build_tool_limit_exceeded_message(
+ thread_count: int,
+ run_count: int,
+ thread_limit: int | None,
+ run_limit: int | None,
+ tool_name: str | None,
+) -> str:
+ """Build a message indicating which tool call limits were exceeded.
+
+ Args:
+ thread_count: Current thread tool call count.
+ run_count: Current run tool call count.
+ thread_limit: Thread tool call limit (if set).
+ run_limit: Run tool call limit (if set).
+ tool_name: Tool name being limited (if specific tool), or None for all tools.
+
+ Returns:
+ A formatted message describing which limits were exceeded.
+ """
+ tool_desc = f"'{tool_name}' tool call" if tool_name else "Tool call"
+ exceeded_limits = []
+ if thread_limit is not None and thread_count >= thread_limit:
+ exceeded_limits.append(f"thread limit ({thread_count}/{thread_limit})")
+ if run_limit is not None and run_count >= run_limit:
+ exceeded_limits.append(f"run limit ({run_count}/{run_limit})")
+
+ return f"{tool_desc} limits exceeded: {', '.join(exceeded_limits)}"
+
+
+class ToolCallLimitExceededError(Exception):
+ """Exception raised when tool call limits are exceeded.
+
+ This exception is raised when the configured exit behavior is 'error'
+ and either the thread or run tool call limit has been exceeded.
+ """
+
+ def __init__(
+ self,
+ thread_count: int,
+ run_count: int,
+ thread_limit: int | None,
+ run_limit: int | None,
+ tool_name: str | None = None,
+ ) -> None:
+ """Initialize the exception with call count information.
+
+ Args:
+ thread_count: Current thread tool call count.
+ run_count: Current run tool call count.
+ thread_limit: Thread tool call limit (if set).
+ run_limit: Run tool call limit (if set).
+ tool_name: Tool name being limited (if specific tool), or None for all tools.
+ """
+ self.thread_count = thread_count
+ self.run_count = run_count
+ self.thread_limit = thread_limit
+ self.run_limit = run_limit
+ self.tool_name = tool_name
+
+ msg = _build_tool_limit_exceeded_message(
+ thread_count, run_count, thread_limit, run_limit, tool_name
+ )
+ super().__init__(msg)
+
+
+class ToolCallLimitMiddleware(AgentMiddleware):
+ """Middleware that tracks tool call counts and enforces limits.
+
+ This middleware monitors the number of tool calls made during agent execution
+ and can terminate the agent when specified limits are reached. It supports
+ both thread-level and run-level call counting with configurable exit behaviors.
+
+ Thread-level: The middleware counts all tool calls in the entire message history
+ and persists this count across multiple runs (invocations) of the agent.
+
+ Run-level: The middleware counts tool calls made after the last HumanMessage,
+ representing the current run (invocation) of the agent.
+
+ Example:
+ ```python
+ from langchain.agents.middleware.tool_call_limit import ToolCallLimitMiddleware
+ from langchain.agents import create_agent
+
+ # Limit all tool calls globally
+ global_limiter = ToolCallLimitMiddleware(thread_limit=20, run_limit=10, exit_behavior="end")
+
+ # Limit a specific tool
+ search_limiter = ToolCallLimitMiddleware(
+ tool_name="search", thread_limit=5, run_limit=3, exit_behavior="end"
+ )
+
+ # Use both in the same agent
+ agent = create_agent("openai:gpt-4o", middleware=[global_limiter, search_limiter])
+
+ result = await agent.invoke({"messages": [HumanMessage("Help me with a task")]})
+ ```
+ """
+
+ def __init__(
+ self,
+ *,
+ tool_name: str | None = None,
+ thread_limit: int | None = None,
+ run_limit: int | None = None,
+ exit_behavior: Literal["end", "error"] = "end",
+ ) -> None:
+ """Initialize the tool call limit middleware.
+
+ Args:
+ tool_name: Name of the specific tool to limit. If None, limits apply
+ to all tools. Defaults to None.
+ thread_limit: Maximum number of tool calls allowed per thread.
+ None means no limit. Defaults to None.
+ run_limit: Maximum number of tool calls allowed per run.
+ None means no limit. Defaults to None.
+ exit_behavior: What to do when limits are exceeded.
+ - "end": Jump to the end of the agent execution and
+ inject an artificial AI message indicating that the limit was exceeded.
+ - "error": Raise a ToolCallLimitExceededError
+ Defaults to "end".
+
+ Raises:
+ ValueError: If both limits are None or if exit_behavior is invalid.
+ """
+ super().__init__()
+
+ if thread_limit is None and run_limit is None:
+ msg = "At least one limit must be specified (thread_limit or run_limit)"
+ raise ValueError(msg)
+
+ if exit_behavior not in ("end", "error"):
+ msg = f"Invalid exit_behavior: {exit_behavior}. Must be 'end' or 'error'"
+ raise ValueError(msg)
+
+ self.tool_name = tool_name
+ self.thread_limit = thread_limit
+ self.run_limit = run_limit
+ self.exit_behavior = exit_behavior
+
+ @property
+ def name(self) -> str:
+ """The name of the middleware instance.
+
+ Includes the tool name if specified to allow multiple instances
+ of this middleware with different tool names.
+ """
+ base_name = self.__class__.__name__
+ if self.tool_name:
+ return f"{base_name}[{self.tool_name}]"
+ return base_name
+
+ @hook_config(can_jump_to=["end"])
+ def before_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None: # noqa: ARG002
+ """Check tool call limits before making a model call.
+
+ Args:
+ state: The current agent state containing messages.
+ runtime: The langgraph runtime.
+
+ Returns:
+ If limits are exceeded and exit_behavior is "end", returns
+ a Command to jump to the end with a limit exceeded message. Otherwise returns None.
+
+ Raises:
+ ToolCallLimitExceededError: If limits are exceeded and exit_behavior
+ is "error".
+ """
+ messages = state.get("messages", [])
+
+ # Count tool calls in entire thread
+ thread_count = _count_tool_calls_in_messages(messages, self.tool_name)
+
+ # Count tool calls in current run (after last HumanMessage)
+ run_messages = _get_run_messages(messages)
+ run_count = _count_tool_calls_in_messages(run_messages, self.tool_name)
+
+ # Check if any limits are exceeded
+ thread_limit_exceeded = self.thread_limit is not None and thread_count >= self.thread_limit
+ run_limit_exceeded = self.run_limit is not None and run_count >= self.run_limit
+
+ if thread_limit_exceeded or run_limit_exceeded:
+ if self.exit_behavior == "error":
+ raise ToolCallLimitExceededError(
+ thread_count=thread_count,
+ run_count=run_count,
+ thread_limit=self.thread_limit,
+ run_limit=self.run_limit,
+ tool_name=self.tool_name,
+ )
+ if self.exit_behavior == "end":
+ # Create a message indicating the limit was exceeded
+ limit_message = _build_tool_limit_exceeded_message(
+ thread_count, run_count, self.thread_limit, self.run_limit, self.tool_name
+ )
+ limit_ai_message = AIMessage(content=limit_message)
+
+ return {"jump_to": "end", "messages": [limit_ai_message]}
+
+ return None
diff --git a/libs/langchain_v1/langchain/agents/middleware/types.py b/libs/langchain_v1/langchain/agents/middleware/types.py
index ac028429b6..d0b0192060 100644
--- a/libs/langchain_v1/langchain/agents/middleware/types.py
+++ b/libs/langchain_v1/langchain/agents/middleware/types.py
@@ -126,6 +126,14 @@ class AgentMiddleware(Generic[StateT, ContextT]):
tools: list[BaseTool]
"""Additional tools registered by the middleware."""
+ @property
+ def name(self) -> str:
+ """The name of the middleware instance.
+
+ Defaults to the class name, but can be overridden for custom naming.
+ """
+ return self.__class__.__name__
+
def before_model(self, state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None:
"""Logic to run before the model is called."""
diff --git a/libs/langchain_v1/langchain/agents/middleware_agent.py b/libs/langchain_v1/langchain/agents/middleware_agent.py
index fb14560850..64341a72b8 100644
--- a/libs/langchain_v1/langchain/agents/middleware_agent.py
+++ b/libs/langchain_v1/langchain/agents/middleware_agent.py
@@ -245,7 +245,7 @@ def create_agent( # noqa: PLR0915
) + middleware_tools
# validate middleware
- assert len({m.__class__.__name__ for m in middleware}) == len(middleware), ( # noqa: S101
+ assert len({m.name for m in middleware}) == len(middleware), ( # noqa: S101
"Please remove duplicate middleware instances."
)
middleware_w_before = [
@@ -548,9 +548,7 @@ def create_agent( # noqa: PLR0915
else None
)
before_node = RunnableCallable(sync_before, async_before)
- graph.add_node(
- f"{m.__class__.__name__}.before_model", before_node, input_schema=state_schema
- )
+ graph.add_node(f"{m.name}.before_model", before_node, input_schema=state_schema)
if (
m.__class__.after_model is not AgentMiddleware.after_model
@@ -569,20 +567,14 @@ def create_agent( # noqa: PLR0915
else None
)
after_node = RunnableCallable(sync_after, async_after)
- graph.add_node(
- f"{m.__class__.__name__}.after_model", after_node, input_schema=state_schema
- )
+ graph.add_node(f"{m.name}.after_model", after_node, input_schema=state_schema)
# add start edge
first_node = (
- f"{middleware_w_before[0].__class__.__name__}.before_model"
- if middleware_w_before
- else "model_request"
+ f"{middleware_w_before[0].name}.before_model" if middleware_w_before else "model_request"
)
last_node = (
- f"{middleware_w_after[0].__class__.__name__}.after_model"
- if middleware_w_after
- else "model_request"
+ f"{middleware_w_after[0].name}.after_model" if middleware_w_after else "model_request"
)
graph.add_edge(START, first_node)
@@ -605,7 +597,7 @@ def create_agent( # noqa: PLR0915
# If after_model, then need to check for can_jump_to
_add_middleware_edge(
graph,
- f"{middleware_w_after[0].__class__.__name__}.after_model",
+ f"{middleware_w_after[0].name}.after_model",
END,
first_node,
can_jump_to=_get_can_jump_to(middleware_w_after[0], "after_model"),
@@ -616,29 +608,29 @@ def create_agent( # noqa: PLR0915
for m1, m2 in itertools.pairwise(middleware_w_before):
_add_middleware_edge(
graph,
- f"{m1.__class__.__name__}.before_model",
- f"{m2.__class__.__name__}.before_model",
+ f"{m1.name}.before_model",
+ f"{m2.name}.before_model",
first_node,
can_jump_to=_get_can_jump_to(m1, "before_model"),
)
# Go directly to model_request after the last before_model
_add_middleware_edge(
graph,
- f"{middleware_w_before[-1].__class__.__name__}.before_model",
+ f"{middleware_w_before[-1].name}.before_model",
"model_request",
first_node,
can_jump_to=_get_can_jump_to(middleware_w_before[-1], "before_model"),
)
if middleware_w_after:
- graph.add_edge("model_request", f"{middleware_w_after[-1].__class__.__name__}.after_model")
+ graph.add_edge("model_request", f"{middleware_w_after[-1].name}.after_model")
for idx in range(len(middleware_w_after) - 1, 0, -1):
m1 = middleware_w_after[idx]
m2 = middleware_w_after[idx - 1]
_add_middleware_edge(
graph,
- f"{m1.__class__.__name__}.after_model",
- f"{m2.__class__.__name__}.after_model",
+ f"{m1.name}.after_model",
+ f"{m2.name}.after_model",
first_node,
can_jump_to=_get_can_jump_to(m1, "after_model"),
)
diff --git a/libs/langchain_v1/tests/unit_tests/agents/test_tool_call_limit.py b/libs/langchain_v1/tests/unit_tests/agents/test_tool_call_limit.py
new file mode 100644
index 0000000000..e0bf1e9efe
--- /dev/null
+++ b/libs/langchain_v1/tests/unit_tests/agents/test_tool_call_limit.py
@@ -0,0 +1,433 @@
+"""Unit tests for ToolCallLimitMiddleware."""
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage, ToolCall, ToolMessage
+from langchain_core.tools import tool
+from langgraph.checkpoint.memory import InMemorySaver
+
+from langchain.agents.middleware_agent import create_agent
+from langchain.agents.middleware.tool_call_limit import (
+ ToolCallLimitExceededError,
+ ToolCallLimitMiddleware,
+ _count_tool_calls_in_messages,
+ _get_run_messages,
+)
+from tests.unit_tests.agents.test_middleware_agent import FakeToolCallingModel
+
+
+def test_count_tool_calls_in_messages():
+ """Test counting tool calls in messages."""
+ # Test with no messages
+ assert _count_tool_calls_in_messages([]) == 0
+
+ # Test with messages but no tool calls
+ messages = [
+ HumanMessage("Hello"),
+ AIMessage("Hi there"),
+ ]
+ assert _count_tool_calls_in_messages(messages) == 0
+
+ # Test with tool calls
+ messages = [
+ HumanMessage("Search for something"),
+ AIMessage(
+ "Searching...",
+ tool_calls=[
+ {"name": "search", "args": {"query": "test"}, "id": "1"},
+ {"name": "calculator", "args": {"expression": "1+1"}, "id": "2"},
+ ],
+ ),
+ ToolMessage("Result 1", tool_call_id="1"),
+ ToolMessage("Result 2", tool_call_id="2"),
+ AIMessage(
+ "More searching...",
+ tool_calls=[
+ {"name": "search", "args": {"query": "another"}, "id": "3"},
+ ],
+ ),
+ ]
+ # Total: 3 tool calls (2 from first AI message, 1 from second)
+ assert _count_tool_calls_in_messages(messages) == 3
+
+ # Test filtering by tool name
+ assert _count_tool_calls_in_messages(messages, tool_name="search") == 2
+ assert _count_tool_calls_in_messages(messages, tool_name="calculator") == 1
+ assert _count_tool_calls_in_messages(messages, tool_name="nonexistent") == 0
+
+
+def test_get_run_messages():
+ """Test extracting run messages after last HumanMessage."""
+ # Test with no messages
+ assert _get_run_messages([]) == []
+
+ # Test with no HumanMessage
+ messages = [
+ AIMessage("Hello"),
+ AIMessage("World"),
+ ]
+ assert _get_run_messages(messages) == messages
+
+ # Test with HumanMessage at the end
+ messages = [
+ AIMessage("Previous"),
+ HumanMessage("New question"),
+ ]
+ assert _get_run_messages(messages) == []
+
+ # Test with messages after HumanMessage
+ messages = [
+ AIMessage("Previous"),
+ ToolMessage("Previous result", tool_call_id="0"),
+ HumanMessage("New question"),
+ AIMessage(
+ "Response",
+ tool_calls=[{"name": "search", "args": {}, "id": "1"}],
+ ),
+ ToolMessage("Result", tool_call_id="1"),
+ ]
+ run_messages = _get_run_messages(messages)
+ assert len(run_messages) == 2
+ assert isinstance(run_messages[0], AIMessage)
+ assert isinstance(run_messages[1], ToolMessage)
+
+
+def test_middleware_initialization_validation():
+ """Test that middleware initialization validates parameters correctly."""
+ # Test that at least one limit must be specified
+ with pytest.raises(ValueError, match="At least one limit must be specified"):
+ ToolCallLimitMiddleware()
+
+ # Test invalid exit behavior
+ with pytest.raises(ValueError, match="Invalid exit_behavior"):
+ ToolCallLimitMiddleware(thread_limit=5, exit_behavior="invalid") # type: ignore[arg-type]
+
+ # Test valid initialization
+ middleware = ToolCallLimitMiddleware(thread_limit=5, run_limit=3)
+ assert middleware.thread_limit == 5
+ assert middleware.run_limit == 3
+ assert middleware.exit_behavior == "end"
+ assert middleware.tool_name is None
+
+ # Test with tool name
+ middleware = ToolCallLimitMiddleware(tool_name="search", thread_limit=5)
+ assert middleware.tool_name == "search"
+ assert middleware.thread_limit == 5
+ assert middleware.run_limit is None
+
+
+def test_middleware_name_property():
+ """Test that the name property includes tool name when specified."""
+ # Test without tool name
+ middleware = ToolCallLimitMiddleware(thread_limit=5)
+ assert middleware.name == "ToolCallLimitMiddleware"
+
+ # Test with tool name
+ middleware = ToolCallLimitMiddleware(tool_name="search", thread_limit=5)
+ assert middleware.name == "ToolCallLimitMiddleware[search]"
+
+ # Test multiple instances with different tool names have unique names
+ middleware1 = ToolCallLimitMiddleware(tool_name="search", thread_limit=5)
+ middleware2 = ToolCallLimitMiddleware(tool_name="calculator", thread_limit=3)
+ assert middleware1.name != middleware2.name
+ assert middleware1.name == "ToolCallLimitMiddleware[search]"
+ assert middleware2.name == "ToolCallLimitMiddleware[calculator]"
+
+
+def test_middleware_unit_functionality():
+ """Test that the middleware works as expected in isolation."""
+ # Test with end behavior - global tool limit
+ middleware = ToolCallLimitMiddleware(thread_limit=3, run_limit=2)
+
+ # Mock runtime (not used in current implementation)
+ runtime = None
+
+ # Test when limits are not exceeded
+ state = {
+ "messages": [
+ HumanMessage("Question"),
+ AIMessage(
+ "Response",
+ tool_calls=[{"name": "search", "args": {}, "id": "1"}],
+ ),
+ ]
+ }
+ result = middleware.before_model(state, runtime) # type: ignore[arg-type]
+ assert result is None
+
+ # Test when thread limit is exceeded
+ state = {
+ "messages": [
+ HumanMessage("Question 1"),
+ AIMessage(
+ "Response 1",
+ tool_calls=[
+ {"name": "search", "args": {}, "id": "1"},
+ {"name": "calculator", "args": {}, "id": "2"},
+ ],
+ ),
+ ToolMessage("Result 1", tool_call_id="1"),
+ ToolMessage("Result 2", tool_call_id="2"),
+ HumanMessage("Question 2"),
+ AIMessage(
+ "Response 2",
+ tool_calls=[{"name": "search", "args": {}, "id": "3"}],
+ ),
+ ]
+ }
+ result = middleware.before_model(state, runtime) # type: ignore[arg-type]
+ assert result is not None
+ assert result["jump_to"] == "end"
+ assert "messages" in result
+ assert len(result["messages"]) == 1
+ assert "thread limit (3/3)" in result["messages"][0].content
+
+ # Test when run limit is exceeded
+ state = {
+ "messages": [
+ HumanMessage("Question"),
+ AIMessage(
+ "Response",
+ tool_calls=[
+ {"name": "search", "args": {}, "id": "1"},
+ {"name": "calculator", "args": {}, "id": "2"},
+ ],
+ ),
+ ]
+ }
+ result = middleware.before_model(state, runtime) # type: ignore[arg-type]
+ assert result is not None
+ assert result["jump_to"] == "end"
+ assert "run limit (2/2)" in result["messages"][0].content
+
+
+def test_middleware_with_specific_tool():
+ """Test middleware that limits a specific tool."""
+ # Limit only the "search" tool
+ middleware = ToolCallLimitMiddleware(tool_name="search", thread_limit=2, run_limit=1)
+
+ runtime = None
+
+ # Test with search tool calls
+ state = {
+ "messages": [
+ HumanMessage("Question"),
+ AIMessage(
+ "Response",
+ tool_calls=[
+ {"name": "search", "args": {}, "id": "1"},
+ {"name": "calculator", "args": {}, "id": "2"},
+ ],
+ ),
+ ]
+ }
+ # Run limit for search is 1, should be exceeded
+ result = middleware.before_model(state, runtime) # type: ignore[arg-type]
+ assert result is not None
+ assert "'search' tool call" in result["messages"][0].content
+ assert "run limit (1/1)" in result["messages"][0].content
+
+ # Test with only calculator calls (should not trigger limit)
+ state = {
+ "messages": [
+ HumanMessage("Question"),
+ AIMessage(
+ "Response",
+ tool_calls=[
+ {"name": "calculator", "args": {}, "id": "1"},
+ {"name": "calculator", "args": {}, "id": "2"},
+ ],
+ ),
+ ]
+ }
+ result = middleware.before_model(state, runtime) # type: ignore[arg-type]
+ assert result is None
+
+
+def test_middleware_error_behavior():
+ """Test middleware with error exit behavior."""
+ middleware = ToolCallLimitMiddleware(thread_limit=2, run_limit=1, exit_behavior="error")
+
+ runtime = None
+
+ # Test exception when thread limit exceeded
+ state = {
+ "messages": [
+ HumanMessage("Q"),
+ AIMessage("R", tool_calls=[{"name": "search", "args": {}, "id": "1"}]),
+ ToolMessage("Result", tool_call_id="1"),
+ AIMessage("R", tool_calls=[{"name": "search", "args": {}, "id": "2"}]),
+ ]
+ }
+ with pytest.raises(ToolCallLimitExceededError) as exc_info:
+ middleware.before_model(state, runtime) # type: ignore[arg-type]
+
+ assert "thread limit (2/2)" in str(exc_info.value)
+ assert exc_info.value.thread_count == 2
+ assert exc_info.value.thread_limit == 2
+
+ # Test exception when run limit exceeded
+ state = {
+ "messages": [
+ HumanMessage("Question"),
+ AIMessage("R", tool_calls=[{"name": "search", "args": {}, "id": "1"}]),
+ ]
+ }
+ with pytest.raises(ToolCallLimitExceededError) as exc_info:
+ middleware.before_model(state, runtime) # type: ignore[arg-type]
+
+ assert "run limit (1/1)" in str(exc_info.value)
+
+
+def test_multiple_middleware_instances():
+ """Test using multiple ToolCallLimitMiddleware instances in the same agent."""
+
+ @tool
+ def search(query: str) -> str:
+ """Search for information."""
+ return f"Results for: {query}"
+
+ @tool
+ def calculator(expression: str) -> str:
+ """Calculate an expression."""
+ return f"Result: {expression}"
+
+ # Create model that makes multiple tool calls
+ model = FakeToolCallingModel(
+ tool_calls=[
+ [
+ ToolCall(name="search", args={"query": "test1"}, id="1"),
+ ToolCall(name="calculator", args={"expression": "1+1"}, id="2"),
+ ],
+ [
+ ToolCall(name="search", args={"query": "test2"}, id="3"),
+ ToolCall(name="calculator", args={"expression": "2+2"}, id="4"),
+ ],
+ [
+ ToolCall(name="search", args={"query": "test3"}, id="5"),
+ ],
+ [],
+ ]
+ )
+
+ # Global limit: max 5 tool calls per thread
+ # Search-specific limit: max 2 search calls per thread
+ global_limiter = ToolCallLimitMiddleware(thread_limit=5)
+ search_limiter = ToolCallLimitMiddleware(tool_name="search", thread_limit=2)
+
+ agent = create_agent(
+ model=model,
+ tools=[search, calculator],
+ middleware=[global_limiter, search_limiter],
+ ).compile(checkpointer=InMemorySaver())
+
+ # First invocation: 2 search calls, 2 calculator calls (4 total)
+ # Should succeed - within both limits
+ result = agent.invoke(
+ {"messages": [HumanMessage("First question")]},
+ {"configurable": {"thread_id": "test_thread"}},
+ )
+ assert len(result["messages"]) > 0
+
+ # Second invocation would add 1 more search call (total 3), exceeding search limit
+ # Should hit the search-specific limit
+ result = agent.invoke(
+ {"messages": [HumanMessage("Second question")]},
+ {"configurable": {"thread_id": "test_thread"}},
+ )
+
+ # Check that the limit was hit
+ last_message = result["messages"][-1]
+ assert isinstance(last_message, AIMessage)
+ assert "'search' tool call" in last_message.content
+ assert "thread limit" in last_message.content
+
+
+def test_run_limit_with_multiple_human_messages():
+ """Test that run limit correctly resets after each HumanMessage."""
+
+ @tool
+ def search(query: str) -> str:
+ """Search for information."""
+ return f"Results for: {query}"
+
+ # Model makes 2 tool calls, then 1 tool call, then no tool calls
+ model = FakeToolCallingModel(
+ tool_calls=[
+ [
+ ToolCall(name="search", args={"query": "test1"}, id="1"),
+ ToolCall(name="search", args={"query": "test2"}, id="2"),
+ ],
+ [ToolCall(name="search", args={"query": "test3"}, id="3")],
+ [],
+ ]
+ )
+
+ # Run limit of 2 tool calls per run
+ middleware = ToolCallLimitMiddleware(run_limit=2)
+
+ agent = create_agent(model=model, tools=[search], middleware=[middleware]).compile(
+ checkpointer=InMemorySaver()
+ )
+
+ thread_config = {"configurable": {"thread_id": "test_thread"}}
+
+ # First run: 2 tool calls, should hit run limit
+ result = agent.invoke({"messages": [HumanMessage("Question 1")]}, thread_config)
+ last_message = result["messages"][-1]
+ assert "run limit (2/2)" in last_message.content
+
+ # Second run: starts fresh, should also hit run limit after 2 calls
+ result = agent.invoke({"messages": [HumanMessage("Question 2")]}, thread_config)
+ last_message = result["messages"][-1]
+ # This should also hit the limit because run count resets
+ assert "run limit (2/2)" in last_message.content
+
+
+def test_exception_error_messages():
+ """Test that exceptions provide clear error messages."""
+ # Test global tool limit
+ middleware = ToolCallLimitMiddleware(thread_limit=3, run_limit=2, exit_behavior="error")
+
+ state = {
+ "messages": [
+ HumanMessage("Q"),
+ AIMessage("R", tool_calls=[{"name": "search", "args": {}, "id": "1"}]),
+ ToolMessage("Result", tool_call_id="1"),
+ AIMessage("R", tool_calls=[{"name": "search", "args": {}, "id": "2"}]),
+ ToolMessage("Result", tool_call_id="2"),
+ AIMessage("R", tool_calls=[{"name": "search", "args": {}, "id": "3"}]),
+ ]
+ }
+
+ with pytest.raises(ToolCallLimitExceededError) as exc_info:
+ middleware.before_model(state, None) # type: ignore[arg-type]
+
+ error_msg = str(exc_info.value)
+ assert "Tool call limits exceeded" in error_msg
+ assert "thread limit (3/3)" in error_msg
+
+ # Test specific tool limit
+ middleware = ToolCallLimitMiddleware(tool_name="search", thread_limit=2, exit_behavior="error")
+
+ state = {
+ "messages": [
+ HumanMessage("Q"),
+ AIMessage(
+ "R",
+ tool_calls=[
+ {"name": "search", "args": {}, "id": "1"},
+ {"name": "calculator", "args": {}, "id": "2"},
+ ],
+ ),
+ ToolMessage("Result", tool_call_id="1"),
+ ToolMessage("Result", tool_call_id="2"),
+ AIMessage("R", tool_calls=[{"name": "search", "args": {}, "id": "3"}]),
+ ]
+ }
+
+ with pytest.raises(ToolCallLimitExceededError) as exc_info:
+ middleware.before_model(state, None) # type: ignore[arg-type]
+
+ error_msg = str(exc_info.value)
+ assert "'search' tool call limits exceeded" in error_msg
+ assert "thread limit (2/2)" in error_msg