langchain.js
    Preparing search index...

    Function toolRetryMiddleware

    • Middleware that automatically retries failed tool calls with configurable backoff.

      Supports retrying on specific exceptions and exponential backoff.

      Parameters

      • config: {
            backoffFactor?: number;
            initialDelayMs?: number;
            jitter?: boolean;
            maxDelayMs?: number;
            maxRetries?: number;
            onFailure?:
                | "raise"
                | "return_message"
                | ((...args: [Error, ...unknown[]]) => string);
            retryOn?:
                | ((...args: [Error, ...unknown[]]) => boolean)
                | (new (...args: any[]) => Error)[];
            tools?: any[];
        } = {}

        Configuration options for the retry middleware

        • OptionalbackoffFactor?: number

          Multiplier for exponential backoff. Each retry waits initialDelayMs * (backoffFactor ** retryNumber) milliseconds. Set to 0.0 for constant delay. Default is 2.0.

        • OptionalinitialDelayMs?: number

          Initial delay in milliseconds before first retry. Default is 1000 (1 second).

        • Optionaljitter?: boolean

          Whether to add random jitter (±25%) to delay to avoid thundering herd. Default is true.

        • OptionalmaxDelayMs?: number

          Maximum delay in milliseconds between retries. Caps exponential backoff growth. Default is 60000 (60 seconds).

        • OptionalmaxRetries?: number

          Maximum number of retry attempts after the initial call. Default is 2 retries (3 total attempts). Must be >= 0.

        • OptionalonFailure?: "raise" | "return_message" | ((...args: [Error, ...unknown[]]) => string)

          Behavior when all retries are exhausted. Options:

          • "return_message" (default): Return a ToolMessage with error details, allowing the LLM to handle the failure and potentially recover.
          • "raise": Re-raise the exception, stopping agent execution.
          • Custom function: Function that takes the exception and returns a string for the ToolMessage content, allowing custom error formatting.
        • OptionalretryOn?:
              | ((...args: [Error, ...unknown[]]) => boolean)
              | (new (...args: any[]) => Error)[]

          Either an array of error constructors to retry on, or a function that takes an error and returns true if it should be retried. Default is to retry on all errors.

        • Optionaltools?: any[]

          Optional list of tools or tool names to apply retry logic to. Can be a list of BaseTool instances or tool name strings. If undefined, applies to all tools. Default is undefined.

      Returns AgentMiddleware

      A middleware instance that handles tool failures with retries

      import { createAgent, toolRetryMiddleware } from "langchain";

      const agent = createAgent({
        model: "openai:gpt-4o",
        tools: [searchTool],
        middleware: [toolRetryMiddleware()],
      });

      import { toolRetryMiddleware } from "langchain";

      const retry = toolRetryMiddleware({
        maxRetries: 4,
        retryOn: [TimeoutError, NetworkError],
        backoffFactor: 1.5,
      });

      function shouldRetry(error: Error): boolean {
        // Only retry on 5xx errors
        if (error.name === "HTTPError" && "statusCode" in error) {
          const statusCode = (error as any).statusCode;
          return 500 <= statusCode && statusCode < 600;
        }
        return false;
      }

      const retry = toolRetryMiddleware({
        maxRetries: 3,
        retryOn: shouldRetry,
      });

      const formatError = (error: Error) =>
        "Database temporarily unavailable. Please try again later.";

      const retry = toolRetryMiddleware({
        maxRetries: 4,
        tools: ["search_database"],
        onFailure: formatError,
      });

      import { tool } from "@langchain/core/tools";
      import { z } from "zod";

      const searchDatabase = tool(
        async ({ query }) => {
          // Search implementation
          return results;
        },
        {
          name: "search_database",
          description: "Search the database",
          schema: z.object({ query: z.string() }),
        }
      );

      const retry = toolRetryMiddleware({
        maxRetries: 4,
        tools: [searchDatabase], // Pass BaseTool instance
      });

      const retry = toolRetryMiddleware({
        maxRetries: 5,
        backoffFactor: 0.0, // No exponential growth
        initialDelayMs: 2000, // Always wait 2 seconds
      });

      const retry = toolRetryMiddleware({
        maxRetries: 2,
        onFailure: "raise", // Re-raise exception instead of returning message
      });

    Settings

    Member Visibility