langchain/dist/agents/middleware/toolCallLimit.d.ts

Typescript bindings for langchain

import { AgentMiddleware } from "./types.js";
import { z } from "zod/v3";
import { InferInteropZodInput } from "@langchain/core/utils/types";

//#region src/agents/middleware/toolCallLimit.d.ts

/**
 * 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.
 */
declare class ToolCallLimitExceededError extends Error {
  /**
   * Current thread tool call count.
   */
  threadCount: number;
  /**
   * Current run tool call count.
   */
  runCount: number;
  /**
   * Thread tool call limit (if set).
   */
  threadLimit: number | undefined;
  /**
   * Run tool call limit (if set).
   */
  runLimit: number | undefined;
  /**
   * Tool name being limited (if specific tool), or undefined for all tools.
   */
  toolName: string | undefined;
  constructor(threadCount: number, runCount: number, threadLimit: number | undefined, runLimit: number | undefined, toolName?: string | undefined);
}
/**
 * Options for configuring the Tool Call Limit middleware.
 */
declare const ToolCallLimitOptionsSchema: z.ZodObject<{
  /**
   * Name of the specific tool to limit. If undefined, limits apply to all tools.
   */
  toolName: z.ZodOptional<z.ZodString>;
  /**
   * Maximum number of tool calls allowed per thread.
   * undefined means no limit.
   */
  threadLimit: z.ZodOptional<z.ZodNumber>;
  /**
   * Maximum number of tool calls allowed per run.
   * undefined means no limit.
   */
  runLimit: z.ZodOptional<z.ZodNumber>;
  /**
   * 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": throws a ToolCallLimitExceededError
   */
  exitBehavior: z.ZodDefault<z.ZodEnum<["end", "error"]>>;
}, "strip", z.ZodTypeAny, {
  toolName?: string | undefined;
  threadLimit?: number | undefined;
  runLimit?: number | undefined;
  exitBehavior: "end" | "error";
}, {
  toolName?: string | undefined;
  threadLimit?: number | undefined;
  runLimit?: number | undefined;
  exitBehavior?: "end" | "error" | undefined;
}>;
type ToolCallLimitConfig = InferInteropZodInput<typeof ToolCallLimitOptionsSchema>;
/**
 * 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.
 *
 * @param options - Configuration options for the middleware
 * @param options.toolName - Name of the specific tool to limit. If undefined, limits apply to all tools.
 * @param options.threadLimit - Maximum number of tool calls allowed per thread. undefined means no limit.
 * @param options.runLimit - Maximum number of tool calls allowed per run. undefined means no limit.
 * @param options.exitBehavior - 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": throws a ToolCallLimitExceededError
 *
 * @throws {Error} If both limits are undefined or if exitBehavior is invalid.
 *
 * @example Limit all tool calls globally
 * ```ts
 * import { toolCallLimitMiddleware } from "@langchain/langchain/agents/middleware";
 * import { createAgent } from "@langchain/langchain/agents";
 *
 * const globalLimiter = toolCallLimitMiddleware({
 *   threadLimit: 20,
 *   runLimit: 10,
 *   exitBehavior: "end"
 * });
 *
 * const agent = createAgent({
 *   model: "openai:gpt-4o",
 *   middleware: [globalLimiter]
 * });
 * ```
 *
 * @example Limit a specific tool
 * ```ts
 * import { toolCallLimitMiddleware } from "@langchain/langchain/agents/middleware";
 * import { createAgent } from "@langchain/langchain/agents";
 *
 * const searchLimiter = toolCallLimitMiddleware({
 *   toolName: "search",
 *   threadLimit: 5,
 *   runLimit: 3,
 *   exitBehavior: "end"
 * });
 *
 * const agent = createAgent({
 *   model: "openai:gpt-4o",
 *   middleware: [searchLimiter]
 * });
 * ```
 *
 * @example Use both in the same agent
 * ```ts
 * import { toolCallLimitMiddleware } from "@langchain/langchain/agents/middleware";
 * import { createAgent } from "@langchain/langchain/agents";
 *
 * const globalLimiter = toolCallLimitMiddleware({
 *   threadLimit: 20,
 *   runLimit: 10,
 *   exitBehavior: "end"
 * });
 *
 * const searchLimiter = toolCallLimitMiddleware({
 *   toolName: "search",
 *   threadLimit: 5,
 *   runLimit: 3,
 *   exitBehavior: "end"
 * });
 *
 * const agent = createAgent({
 *   model: "openai:gpt-4o",
 *   middleware: [globalLimiter, searchLimiter]
 * });
 * ```
 */
declare function toolCallLimitMiddleware(options: ToolCallLimitConfig): AgentMiddleware<undefined, undefined, any>;
//#endregion
export { ToolCallLimitConfig, ToolCallLimitExceededError, toolCallLimitMiddleware };
//# sourceMappingURL=toolCallLimit.d.ts.map