feat(langchain/createAgent): implement retry model request hook in middleware

[christian-bromann]

This PR implements the retryModelRequest middleware hook and ModelFallbackMiddleware, mirroring the Python implementation.

Changes

1. New retryModelRequest Middleware Hook

Added a new optional hook to the AgentMiddleware interface that allows middleware to intercept model invocation errors and optionally retry with modified requests:

retryModelRequest?(
  error: Error,
  request: ModelRequest,
  state: AgentBuiltInState,
  runtime: Runtime,
  attempt: number
): Promise<ModelRequest | void> | ModelRequest | void;

• Parameters:

  • error: The exception that occurred during model invocation
  • request: The original model request that failed
  • state: The current agent state
  • runtime: The runtime context
  • attempt: The current attempt number (1-indexed)

• Return value:

  • ModelRequest: Modified request to retry with
  • void: Propagate the error (no retry)

2. ModelFallbackMiddleware

New middleware that provides automatic model fallback on errors:

import { createAgent, modelFallbackMiddleware } from "langchain";

const agent = createAgent({
  model: "openai:gpt-4o",  // Primary model
  middleware: [
    modelFallbackMiddleware(
      "openai:gpt-4o-mini",      // First fallback
      "anthropic:claude-3-5-sonnet-20241022"  // Second fallback
    )
  ],
  tools: [],
});

// If gpt-4o fails, automatically tries gpt-4o-mini, then claude
const result = await agent.invoke({
  messages: [{ role: "user", content: "Hello" }]
});

Features:

• Accepts variadic arguments for fallback models (strings or model instances)
• Tries each fallback model in sequence until one succeeds or all are exhausted
• Lazy initialization of model instances from strings

3. AgentNode Retry Logic

Modified AgentNode#invokeModel to implement retry loop:

• Wraps model invocation in try-catch with retry loop
• On error, iterates through middleware with retryModelRequest hooks
• First middleware that returns a modified request triggers a retry
• Hard limit of 100 attempts prevents infinite loops from buggy middleware
• If no middleware wants to retry, re-raises the original error

[changeset-bot]

⚠️ No Changeset found

Latest commit: 012373c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
langchainjs-api-refs	Ignored			Oct 5, 2025 11:59pm
langchainjs-docs	Ignored			Oct 5, 2025 11:59pm