Class●Since v1.0

ToolCallLimitMiddleware

Track tool call counts and enforces limits during agent execution.

This middleware monitors the number of tool calls made and can terminate or restrict execution when limits are exceeded. It supports both thread-level (persistent across runs) and run-level (per invocation) call counting.

ToolCallLimitMiddleware(
  self,
  *,
  tool_name: str | None = None,
  thread_limit: int | None = None,
  run_limit: int | None = None,
  exit_behavior: ExitBehavior = 'continue'
)

Bases

AgentMiddleware[ToolCallLimitState[ResponseT], ContextT, ResponseT]

Configuration:

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).

Parameters

Name	Type	Description
`tool_name`	`str \| None`	Default:`None` Name of the specific tool to limit. If `None`, limits apply to all tools.
`thread_limit`	`int \| None`	Default:`None` Maximum number of tool calls allowed per thread. `None` means no limit.
`run_limit`	`int \| None`	Default:`None` Maximum number of tool calls allowed per run. `None` means no limit.
`exit_behavior`	`ExitBehavior`	Default:`'continue'` How to handle when limits are exceeded. `'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.