langchain 1.0.5 → 1.1.0

package/dist/agents/middleware/index.cjs

@@ -1,7 +1,6 @@
 const require_utils = require('./utils.cjs');
-const require_summarization = require('./summarization.cjs');
 const require_hitl = require('./hitl.cjs');
-const require_promptCaching = require('./promptCaching.cjs');
+const require_summarization = require('./summarization.cjs');
 const require_dynamicSystemPrompt = require('./dynamicSystemPrompt.cjs');
 const require_llmToolSelector = require('./llmToolSelector.cjs');
 const require_pii = require('./pii.cjs');
@@ -11,5 +10,8 @@ const require_toolCallLimit = require('./toolCallLimit.cjs');
 const require_todoListMiddleware = require('./todoListMiddleware.cjs');
 const require_modelCallLimit = require('./modelCallLimit.cjs');
 const require_modelFallback = require('./modelFallback.cjs');
+const require_modelRetry = require('./modelRetry.cjs');
 const require_toolRetry = require('./toolRetry.cjs');
 const require_toolEmulator = require('./toolEmulator.cjs');
+const require_moderation = require('./provider/openai/moderation.cjs');
+const require_promptCaching = require('./provider/anthropic/promptCaching.cjs');

package/dist/agents/middleware/index.d.ts

@@ -0,0 +1,18 @@
+import { AgentMiddleware } from "./types.js";
+import { Action, ActionRequest, ApproveDecision, Decision, DecisionType, DescriptionFactory, EditDecision, HITLRequest, HITLResponse, HumanInTheLoopMiddlewareConfig, InterruptOnConfig, RejectDecision, ReviewConfig, humanInTheLoopMiddleware } from "./hitl.js";
+import { SummarizationMiddlewareConfig, TokenCounter, summarizationMiddleware } from "./summarization.js";
+import { DynamicSystemPromptMiddlewareConfig, dynamicSystemPromptMiddleware } from "./dynamicSystemPrompt.js";
+import { LLMToolSelectorConfig, llmToolSelectorMiddleware } from "./llmToolSelector.js";
+import { BuiltInPIIType, PIIDetectionError, PIIDetector, PIIMatch, PIIMiddlewareConfig, PIIStrategy, RedactionRuleConfig, ResolvedRedactionRule, applyStrategy, detectCreditCard, detectEmail, detectIP, detectMacAddress, detectUrl, piiMiddleware, resolveRedactionRule } from "./pii.js";
+import { PIIRedactionMiddlewareConfig, piiRedactionMiddleware } from "./piiRedaction.js";
+import { ClearToolUsesEdit, ClearToolUsesEditConfig, ContextEdit, ContextEditingMiddlewareConfig, contextEditingMiddleware } from "./contextEditing.js";
+import { ToolCallLimitConfig, ToolCallLimitExceededError, toolCallLimitMiddleware } from "./toolCallLimit.js";
+import { TODO_LIST_MIDDLEWARE_SYSTEM_PROMPT, TodoListMiddlewareOptions, todoListMiddleware } from "./todoListMiddleware.js";
+import { ModelCallLimitMiddlewareConfig, modelCallLimitMiddleware } from "./modelCallLimit.js";
+import { modelFallbackMiddleware } from "./modelFallback.js";
+import { ModelRetryMiddlewareConfig, modelRetryMiddleware } from "./modelRetry.js";
+import { ToolRetryMiddlewareConfig, toolRetryMiddleware } from "./toolRetry.js";
+import { ToolEmulatorOptions, toolEmulatorMiddleware } from "./toolEmulator.js";
+import { OpenAIModerationMiddlewareOptions, openAIModerationMiddleware } from "./provider/openai/moderation.js";
+import { PromptCachingMiddlewareConfig, anthropicPromptCachingMiddleware } from "./provider/anthropic/promptCaching.js";
+import { countTokensApproximately } from "./utils.js";

package/dist/agents/middleware/index.js

@@ -1,7 +1,6 @@
 import { countTokensApproximately } from "./utils.js";
-import { summarizationMiddleware } from "./summarization.js";
 import { humanInTheLoopMiddleware } from "./hitl.js";
-import { anthropicPromptCachingMiddleware } from "./promptCaching.js";
+import { summarizationMiddleware } from "./summarization.js";
 import { dynamicSystemPromptMiddleware } from "./dynamicSystemPrompt.js";
 import { llmToolSelectorMiddleware } from "./llmToolSelector.js";
 import { PIIDetectionError, applyStrategy, detectCreditCard, detectEmail, detectIP, detectMacAddress, detectUrl, piiMiddleware, resolveRedactionRule } from "./pii.js";
@@ -11,5 +10,8 @@ import { ToolCallLimitExceededError, toolCallLimitMiddleware } from "./toolCallL
 import { TODO_LIST_MIDDLEWARE_SYSTEM_PROMPT, todoListMiddleware } from "./todoListMiddleware.js";
 import { modelCallLimitMiddleware } from "./modelCallLimit.js";
 import { modelFallbackMiddleware } from "./modelFallback.js";
+import { modelRetryMiddleware } from "./modelRetry.js";
 import { toolRetryMiddleware } from "./toolRetry.js";
 import { toolEmulatorMiddleware } from "./toolEmulator.js";
+import { openAIModerationMiddleware } from "./provider/openai/moderation.js";
+import { anthropicPromptCachingMiddleware } from "./provider/anthropic/promptCaching.js";

package/dist/agents/middleware/modelRetry.cjs

@@ -0,0 +1,162 @@
+const require_rolldown_runtime = require('../../_virtual/rolldown_runtime.cjs');
+const require_utils = require('./utils.cjs');
+const require_middleware = require('../middleware.cjs');
+const require_constants = require('./constants.cjs');
+const require_error = require('./error.cjs');
+const __langchain_core_messages = require_rolldown_runtime.__toESM(require("@langchain/core/messages"));
+const zod_v3 = require_rolldown_runtime.__toESM(require("zod/v3"));
+
+//#region src/agents/middleware/modelRetry.ts
+/**
+* Configuration options for the Model Retry Middleware.
+*/
+const ModelRetryMiddlewareOptionsSchema = zod_v3.z.object({ onFailure: zod_v3.z.union([
+	zod_v3.z.literal("error"),
+	zod_v3.z.literal("continue"),
+	zod_v3.z.function().args(zod_v3.z.instanceof(Error)).returns(zod_v3.z.string())
+]).default("continue") }).merge(require_constants.RetrySchema);
+/**
+* Middleware that automatically retries failed model calls with configurable backoff.
+*
+* Supports retrying on specific exceptions and exponential backoff.
+*
+* @example Basic usage with default settings (2 retries, exponential backoff)
+* ```ts
+* import { createAgent, modelRetryMiddleware } from "langchain";
+*
+* const agent = createAgent({
+*   model: "openai:gpt-4o",
+*   tools: [searchTool],
+*   middleware: [modelRetryMiddleware()],
+* });
+* ```
+*
+* @example Retry specific exceptions only
+* ```ts
+* import { modelRetryMiddleware } from "langchain";
+*
+* const retry = modelRetryMiddleware({
+*   maxRetries: 4,
+*   retryOn: [TimeoutError, NetworkError],
+*   backoffFactor: 1.5,
+* });
+* ```
+*
+* @example Custom exception filtering
+* ```ts
+* function shouldRetry(error: Error): boolean {
+*   // Only retry on rate limit errors
+*   if (error.name === "RateLimitError") {
+*     return true;
+*   }
+*   // Or check for specific HTTP status codes
+*   if (error.name === "HTTPError" && "statusCode" in error) {
+*     const statusCode = (error as any).statusCode;
+*     return statusCode === 429 || statusCode === 503;
+*   }
+*   return false;
+* }
+*
+* const retry = modelRetryMiddleware({
+*   maxRetries: 3,
+*   retryOn: shouldRetry,
+* });
+* ```
+*
+* @example Return error message instead of raising
+* ```ts
+* const retry = modelRetryMiddleware({
+*   maxRetries: 4,
+*   onFailure: "continue", // Return AIMessage with error instead of throwing
+* });
+* ```
+*
+* @example Custom error message formatting
+* ```ts
+* const formatError = (error: Error) =>
+*   `Model call failed: ${error.message}. Please try again later.`;
+*
+* const retry = modelRetryMiddleware({
+*   maxRetries: 4,
+*   onFailure: formatError,
+* });
+* ```
+*
+* @example Constant backoff (no exponential growth)
+* ```ts
+* const retry = modelRetryMiddleware({
+*   maxRetries: 5,
+*   backoffFactor: 0.0, // No exponential growth
+*   initialDelayMs: 2000, // Always wait 2 seconds
+* });
+* ```
+*
+* @example Raise exception on failure
+* ```ts
+* const retry = modelRetryMiddleware({
+*   maxRetries: 2,
+*   onFailure: "error", // Re-raise exception instead of returning message
+* });
+* ```
+*
+* @param config - Configuration options for the retry middleware
+* @returns A middleware instance that handles model failures with retries
+*/
+function modelRetryMiddleware(config = {}) {
+	const { success, error, data } = ModelRetryMiddlewareOptionsSchema.safeParse(config);
+	if (!success) throw new require_error.InvalidRetryConfigError(error);
+	const { maxRetries, retryOn, onFailure, backoffFactor, initialDelayMs, maxDelayMs, jitter } = data;
+	/**
+	* Check if the exception should trigger a retry.
+	*/
+	const shouldRetryException = (error$1) => {
+		if (typeof retryOn === "function") return retryOn(error$1);
+		return retryOn.some((ErrorConstructor) => error$1.constructor === ErrorConstructor);
+	};
+	const delayConfig = {
+		backoffFactor,
+		initialDelayMs,
+		maxDelayMs,
+		jitter
+	};
+	/**
+	* Format the failure message when retries are exhausted.
+	*/
+	const formatFailureMessage = (error$1, attemptsMade) => {
+		const errorType = error$1.constructor.name;
+		const attemptWord = attemptsMade === 1 ? "attempt" : "attempts";
+		return `Model call failed after ${attemptsMade} ${attemptWord} with ${errorType}: ${error$1.message}`;
+	};
+	/**
+	* Handle failure when all retries are exhausted.
+	*/
+	const handleFailure = (error$1, attemptsMade) => {
+		if (onFailure === "error") throw error$1;
+		let content;
+		if (typeof onFailure === "function") content = onFailure(error$1);
+		else content = formatFailureMessage(error$1, attemptsMade);
+		return new __langchain_core_messages.AIMessage({ content });
+	};
+	return require_middleware.createMiddleware({
+		name: "modelRetryMiddleware",
+		contextSchema: ModelRetryMiddlewareOptionsSchema,
+		wrapModelCall: async (request, handler) => {
+			for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+				return await handler(request);
+			} catch (error$1) {
+				const attemptsMade = attempt + 1;
+				const err = error$1 && typeof error$1 === "object" && "message" in error$1 ? error$1 : new Error(String(error$1));
+				if (!shouldRetryException(err)) return handleFailure(err, attemptsMade);
+				if (attempt < maxRetries) {
+					const delay = require_utils.calculateRetryDelay(delayConfig, attempt);
+					if (delay > 0) await require_utils.sleep(delay);
+				} else return handleFailure(err, attemptsMade);
+			}
+			throw new Error("Unexpected: retry loop completed without returning");
+		}
+	});
+}
+
+//#endregion
+exports.modelRetryMiddleware = modelRetryMiddleware;
+//# sourceMappingURL=modelRetry.cjs.map

package/dist/agents/middleware/modelRetry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelRetry.cjs","names":["z","RetrySchema","config: ModelRetryMiddlewareConfig","InvalidRetryConfigError","error: Error","error","attemptsMade: number","content: string","AIMessage","createMiddleware","calculateRetryDelay","sleep"],"sources":["../../../src/agents/middleware/modelRetry.ts"],"sourcesContent":["/**\n * Model retry middleware for agents.\n */\nimport { z } from \"zod/v3\";\nimport { AIMessage } from \"@langchain/core/messages\";\n\nimport { createMiddleware } from \"../middleware.js\";\nimport type { AgentMiddleware } from \"./types.js\";\nimport { sleep, calculateRetryDelay } from \"./utils.js\";\nimport { RetrySchema } from \"./constants.js\";\nimport { InvalidRetryConfigError } from \"./error.js\";\n\n/**\n * Configuration options for the Model Retry Middleware.\n */\nexport const ModelRetryMiddlewareOptionsSchema = z\n  .object({\n    /**\n     * Behavior when all retries are exhausted. Options:\n     * - `\"continue\"` (default): Return an AIMessage with error details, allowing\n     *   the agent to potentially handle the failure gracefully.\n     * - `\"error\"`: Re-raise the exception, stopping agent execution.\n     * - Custom function: Function that takes the exception and returns a string\n     *   for the AIMessage content, allowing custom error formatting.\n     */\n    onFailure: z\n      .union([\n        z.literal(\"error\"),\n        z.literal(\"continue\"),\n        z.function().args(z.instanceof(Error)).returns(z.string()),\n      ])\n      .default(\"continue\"),\n  })\n  .merge(RetrySchema);\n\nexport type ModelRetryMiddlewareConfig = z.input<\n  typeof ModelRetryMiddlewareOptionsSchema\n>;\n\n/**\n * Middleware that automatically retries failed model calls with configurable backoff.\n *\n * Supports retrying on specific exceptions and exponential backoff.\n *\n * @example Basic usage with default settings (2 retries, exponential backoff)\n * ```ts\n * import { createAgent, modelRetryMiddleware } from \"langchain\";\n *\n * const agent = createAgent({\n *   model: \"openai:gpt-4o\",\n *   tools: [searchTool],\n *   middleware: [modelRetryMiddleware()],\n * });\n * ```\n *\n * @example Retry specific exceptions only\n * ```ts\n * import { modelRetryMiddleware } from \"langchain\";\n *\n * const retry = modelRetryMiddleware({\n *   maxRetries: 4,\n *   retryOn: [TimeoutError, NetworkError],\n *   backoffFactor: 1.5,\n * });\n * ```\n *\n * @example Custom exception filtering\n * ```ts\n * function shouldRetry(error: Error): boolean {\n *   // Only retry on rate limit errors\n *   if (error.name === \"RateLimitError\") {\n *     return true;\n *   }\n *   // Or check for specific HTTP status codes\n *   if (error.name === \"HTTPError\" && \"statusCode\" in error) {\n *     const statusCode = (error as any).statusCode;\n *     return statusCode === 429 || statusCode === 503;\n *   }\n *   return false;\n * }\n *\n * const retry = modelRetryMiddleware({\n *   maxRetries: 3,\n *   retryOn: shouldRetry,\n * });\n * ```\n *\n * @example Return error message instead of raising\n * ```ts\n * const retry = modelRetryMiddleware({\n *   maxRetries: 4,\n *   onFailure: \"continue\", // Return AIMessage with error instead of throwing\n * });\n * ```\n *\n * @example Custom error message formatting\n * ```ts\n * const formatError = (error: Error) =>\n *   `Model call failed: ${error.message}. Please try again later.`;\n *\n * const retry = modelRetryMiddleware({\n *   maxRetries: 4,\n *   onFailure: formatError,\n * });\n * ```\n *\n * @example Constant backoff (no exponential growth)\n * ```ts\n * const retry = modelRetryMiddleware({\n *   maxRetries: 5,\n *   backoffFactor: 0.0, // No exponential growth\n *   initialDelayMs: 2000, // Always wait 2 seconds\n * });\n * ```\n *\n * @example Raise exception on failure\n * ```ts\n * const retry = modelRetryMiddleware({\n *   maxRetries: 2,\n *   onFailure: \"error\", // Re-raise exception instead of returning message\n * });\n * ```\n *\n * @param config - Configuration options for the retry middleware\n * @returns A middleware instance that handles model failures with retries\n */\nexport function modelRetryMiddleware(\n  config: ModelRetryMiddlewareConfig = {}\n): AgentMiddleware {\n  const { success, error, data } =\n    ModelRetryMiddlewareOptionsSchema.safeParse(config);\n  if (!success) {\n    throw new InvalidRetryConfigError(error);\n  }\n  const {\n    maxRetries,\n    retryOn,\n    onFailure,\n    backoffFactor,\n    initialDelayMs,\n    maxDelayMs,\n    jitter,\n  } = data;\n\n  /**\n   * Check if the exception should trigger a retry.\n   */\n  const shouldRetryException = (error: Error): boolean => {\n    if (typeof retryOn === \"function\") {\n      return retryOn(error);\n    }\n    // retryOn is an array of error constructors\n    return retryOn.some(\n      (ErrorConstructor) => error.constructor === ErrorConstructor\n    );\n  };\n\n  // Use the exported calculateRetryDelay function with our config\n  const delayConfig = { backoffFactor, initialDelayMs, maxDelayMs, jitter };\n\n  /**\n   * Format the failure message when retries are exhausted.\n   */\n  const formatFailureMessage = (error: Error, attemptsMade: number): string => {\n    const errorType = error.constructor.name;\n    const attemptWord = attemptsMade === 1 ? \"attempt\" : \"attempts\";\n    return `Model call failed after ${attemptsMade} ${attemptWord} with ${errorType}: ${error.message}`;\n  };\n\n  /**\n   * Handle failure when all retries are exhausted.\n   */\n  const handleFailure = (error: Error, attemptsMade: number): AIMessage => {\n    if (onFailure === \"error\") {\n      throw error;\n    }\n\n    let content: string;\n    if (typeof onFailure === \"function\") {\n      content = onFailure(error);\n    } else {\n      content = formatFailureMessage(error, attemptsMade);\n    }\n\n    return new AIMessage({\n      content,\n    });\n  };\n\n  return createMiddleware({\n    name: \"modelRetryMiddleware\",\n    contextSchema: ModelRetryMiddlewareOptionsSchema,\n    wrapModelCall: async (request, handler) => {\n      // Initial attempt + retries\n      for (let attempt = 0; attempt <= maxRetries; attempt++) {\n        try {\n          return await handler(request);\n        } catch (error) {\n          const attemptsMade = attempt + 1; // attempt is 0-indexed\n\n          // Ensure error is an Error instance\n          const err =\n            error && typeof error === \"object\" && \"message\" in error\n              ? (error as Error)\n              : new Error(String(error));\n\n          // Check if we should retry this exception\n          if (!shouldRetryException(err)) {\n            // Exception is not retryable, handle failure immediately\n            return handleFailure(err, attemptsMade);\n          }\n\n          // Check if we have more retries left\n          if (attempt < maxRetries) {\n            // Calculate and apply backoff delay\n            const delay = calculateRetryDelay(delayConfig, attempt);\n            if (delay > 0) {\n              await sleep(delay);\n            }\n            // Continue to next retry\n          } else {\n            // No more retries, handle failure\n            return handleFailure(err, attemptsMade);\n          }\n        }\n      }\n\n      // Unreachable: loop always returns via handler success or handleFailure\n      throw new Error(\"Unexpected: retry loop completed without returning\");\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;AAeA,MAAa,oCAAoCA,SAC9C,OAAO,EASN,WAAWA,SACR,MAAM;CACLA,SAAE,QAAQ,QAAQ;CAClBA,SAAE,QAAQ,WAAW;CACrBA,SAAE,UAAU,CAAC,KAAKA,SAAE,WAAW,MAAM,CAAC,CAAC,QAAQA,SAAE,QAAQ,CAAC;AAC3D,EAAC,CACD,QAAQ,WAAW,CACvB,EAAC,CACD,MAAMC,8BAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6FrB,SAAgB,qBACdC,SAAqC,CAAE,GACtB;CACjB,MAAM,EAAE,SAAS,OAAO,MAAM,GAC5B,kCAAkC,UAAU,OAAO;AACrD,KAAI,CAAC,QACH,OAAM,IAAIC,sCAAwB;CAEpC,MAAM,EACJ,YACA,SACA,WACA,eACA,gBACA,YACA,QACD,GAAG;;;;CAKJ,MAAM,uBAAuB,CAACC,YAA0B;AACtD,MAAI,OAAO,YAAY,WACrB,QAAO,QAAQC,QAAM;AAGvB,SAAO,QAAQ,KACb,CAAC,qBAAqBA,QAAM,gBAAgB,iBAC7C;CACF;CAGD,MAAM,cAAc;EAAE;EAAe;EAAgB;EAAY;CAAQ;;;;CAKzE,MAAM,uBAAuB,CAACD,SAAcE,iBAAiC;EAC3E,MAAM,YAAYD,QAAM,YAAY;EACpC,MAAM,cAAc,iBAAiB,IAAI,YAAY;AACrD,SAAO,CAAC,wBAAwB,EAAE,aAAa,CAAC,EAAE,YAAY,MAAM,EAAE,UAAU,EAAE,EAAEA,QAAM,SAAS;CACpG;;;;CAKD,MAAM,gBAAgB,CAACD,SAAcE,iBAAoC;AACvE,MAAI,cAAc,QAChB,OAAMD;EAGR,IAAIE;AACJ,MAAI,OAAO,cAAc,YACvB,UAAU,UAAUF,QAAM;OAE1B,UAAU,qBAAqBA,SAAO,aAAa;AAGrD,SAAO,IAAIG,oCAAU,EACnB,QACD;CACF;AAED,QAAOC,oCAAiB;EACtB,MAAM;EACN,eAAe;EACf,eAAe,OAAO,SAAS,YAAY;AAEzC,QAAK,IAAI,UAAU,GAAG,WAAW,YAAY,UAC3C,KAAI;AACF,WAAO,MAAM,QAAQ,QAAQ;GAC9B,SAAQJ,SAAO;IACd,MAAM,eAAe,UAAU;IAG/B,MAAM,MACJA,WAAS,OAAOA,YAAU,YAAY,aAAaA,UAC9CA,UACD,IAAI,MAAM,OAAOA,QAAM;AAG7B,QAAI,CAAC,qBAAqB,IAAI,CAE5B,QAAO,cAAc,KAAK,aAAa;AAIzC,QAAI,UAAU,YAAY;KAExB,MAAM,QAAQK,kCAAoB,aAAa,QAAQ;AACvD,SAAI,QAAQ,GACV,MAAMC,oBAAM,MAAM;IAGrB,MAEC,QAAO,cAAc,KAAK,aAAa;GAE1C;AAIH,SAAM,IAAI,MAAM;EACjB;CACF,EAAC;AACH"}

package/dist/agents/middleware/modelRetry.d.cts

@@ -0,0 +1,134 @@
+import { AgentMiddleware } from "./types.cjs";
+import { z } from "zod/v3";
+
+//#region src/agents/middleware/modelRetry.d.ts
+
+/**
+ * Configuration options for the Model Retry Middleware.
+ */
+declare const ModelRetryMiddlewareOptionsSchema: z.ZodObject<{
+  /**
+   * Behavior when all retries are exhausted. Options:
+   * - `"continue"` (default): Return an AIMessage with error details, allowing
+   *   the agent to potentially handle the failure gracefully.
+   * - `"error"`: Re-raise the exception, stopping agent execution.
+   * - Custom function: Function that takes the exception and returns a string
+   *   for the AIMessage content, allowing custom error formatting.
+   */
+  onFailure: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<"error">, z.ZodLiteral<"continue">, z.ZodFunction<z.ZodTuple<[z.ZodType<Error, z.ZodTypeDef, Error>], z.ZodUnknown>, z.ZodString>]>>;
+} & {
+  maxRetries: z.ZodDefault<z.ZodNumber>;
+  retryOn: z.ZodDefault<z.ZodUnion<[z.ZodFunction<z.ZodTuple<[z.ZodType<Error, z.ZodTypeDef, Error>], z.ZodUnknown>, z.ZodBoolean>, z.ZodArray<z.ZodType<new (...args: any[]) => Error, z.ZodTypeDef, new (...args: any[]) => Error>, "many">]>>;
+  backoffFactor: z.ZodDefault<z.ZodNumber>;
+  initialDelayMs: z.ZodDefault<z.ZodNumber>;
+  maxDelayMs: z.ZodDefault<z.ZodNumber>;
+  jitter: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+  maxRetries: number;
+  retryOn: (new (...args: any[]) => Error)[] | ((args_0: Error, ...args: unknown[]) => boolean);
+  backoffFactor: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  jitter: boolean;
+  onFailure: "continue" | "error" | ((args_0: Error, ...args: unknown[]) => string);
+}, {
+  maxRetries?: number | undefined;
+  retryOn?: (new (...args: any[]) => Error)[] | ((args_0: Error, ...args: unknown[]) => boolean) | undefined;
+  backoffFactor?: number | undefined;
+  initialDelayMs?: number | undefined;
+  maxDelayMs?: number | undefined;
+  jitter?: boolean | undefined;
+  onFailure?: "continue" | "error" | ((args_0: Error, ...args: unknown[]) => string) | undefined;
+}>;
+type ModelRetryMiddlewareConfig = z.input<typeof ModelRetryMiddlewareOptionsSchema>;
+/**
+ * Middleware that automatically retries failed model calls with configurable backoff.
+ *
+ * Supports retrying on specific exceptions and exponential backoff.
+ *
+ * @example Basic usage with default settings (2 retries, exponential backoff)
+ * ```ts
+ * import { createAgent, modelRetryMiddleware } from "langchain";
+ *
+ * const agent = createAgent({
+ *   model: "openai:gpt-4o",
+ *   tools: [searchTool],
+ *   middleware: [modelRetryMiddleware()],
+ * });
+ * ```
+ *
+ * @example Retry specific exceptions only
+ * ```ts
+ * import { modelRetryMiddleware } from "langchain";
+ *
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 4,
+ *   retryOn: [TimeoutError, NetworkError],
+ *   backoffFactor: 1.5,
+ * });
+ * ```
+ *
+ * @example Custom exception filtering
+ * ```ts
+ * function shouldRetry(error: Error): boolean {
+ *   // Only retry on rate limit errors
+ *   if (error.name === "RateLimitError") {
+ *     return true;
+ *   }
+ *   // Or check for specific HTTP status codes
+ *   if (error.name === "HTTPError" && "statusCode" in error) {
+ *     const statusCode = (error as any).statusCode;
+ *     return statusCode === 429 || statusCode === 503;
+ *   }
+ *   return false;
+ * }
+ *
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 3,
+ *   retryOn: shouldRetry,
+ * });
+ * ```
+ *
+ * @example Return error message instead of raising
+ * ```ts
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 4,
+ *   onFailure: "continue", // Return AIMessage with error instead of throwing
+ * });
+ * ```
+ *
+ * @example Custom error message formatting
+ * ```ts
+ * const formatError = (error: Error) =>
+ *   `Model call failed: ${error.message}. Please try again later.`;
+ *
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 4,
+ *   onFailure: formatError,
+ * });
+ * ```
+ *
+ * @example Constant backoff (no exponential growth)
+ * ```ts
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 5,
+ *   backoffFactor: 0.0, // No exponential growth
+ *   initialDelayMs: 2000, // Always wait 2 seconds
+ * });
+ * ```
+ *
+ * @example Raise exception on failure
+ * ```ts
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 2,
+ *   onFailure: "error", // Re-raise exception instead of returning message
+ * });
+ * ```
+ *
+ * @param config - Configuration options for the retry middleware
+ * @returns A middleware instance that handles model failures with retries
+ */
+declare function modelRetryMiddleware(config?: ModelRetryMiddlewareConfig): AgentMiddleware;
+//#endregion
+export { ModelRetryMiddlewareConfig, modelRetryMiddleware };
+//# sourceMappingURL=modelRetry.d.cts.map

package/dist/agents/middleware/modelRetry.d.ts

@@ -0,0 +1,134 @@
+import { AgentMiddleware } from "./types.js";
+import { z } from "zod/v3";
+
+//#region src/agents/middleware/modelRetry.d.ts
+
+/**
+ * Configuration options for the Model Retry Middleware.
+ */
+declare const ModelRetryMiddlewareOptionsSchema: z.ZodObject<{
+  /**
+   * Behavior when all retries are exhausted. Options:
+   * - `"continue"` (default): Return an AIMessage with error details, allowing
+   *   the agent to potentially handle the failure gracefully.
+   * - `"error"`: Re-raise the exception, stopping agent execution.
+   * - Custom function: Function that takes the exception and returns a string
+   *   for the AIMessage content, allowing custom error formatting.
+   */
+  onFailure: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<"error">, z.ZodLiteral<"continue">, z.ZodFunction<z.ZodTuple<[z.ZodType<Error, z.ZodTypeDef, Error>], z.ZodUnknown>, z.ZodString>]>>;
+} & {
+  maxRetries: z.ZodDefault<z.ZodNumber>;
+  retryOn: z.ZodDefault<z.ZodUnion<[z.ZodFunction<z.ZodTuple<[z.ZodType<Error, z.ZodTypeDef, Error>], z.ZodUnknown>, z.ZodBoolean>, z.ZodArray<z.ZodType<new (...args: any[]) => Error, z.ZodTypeDef, new (...args: any[]) => Error>, "many">]>>;
+  backoffFactor: z.ZodDefault<z.ZodNumber>;
+  initialDelayMs: z.ZodDefault<z.ZodNumber>;
+  maxDelayMs: z.ZodDefault<z.ZodNumber>;
+  jitter: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+  maxRetries: number;
+  retryOn: (new (...args: any[]) => Error)[] | ((args_0: Error, ...args: unknown[]) => boolean);
+  backoffFactor: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  jitter: boolean;
+  onFailure: "continue" | "error" | ((args_0: Error, ...args: unknown[]) => string);
+}, {
+  maxRetries?: number | undefined;
+  retryOn?: (new (...args: any[]) => Error)[] | ((args_0: Error, ...args: unknown[]) => boolean) | undefined;
+  backoffFactor?: number | undefined;
+  initialDelayMs?: number | undefined;
+  maxDelayMs?: number | undefined;
+  jitter?: boolean | undefined;
+  onFailure?: "continue" | "error" | ((args_0: Error, ...args: unknown[]) => string) | undefined;
+}>;
+type ModelRetryMiddlewareConfig = z.input<typeof ModelRetryMiddlewareOptionsSchema>;
+/**
+ * Middleware that automatically retries failed model calls with configurable backoff.
+ *
+ * Supports retrying on specific exceptions and exponential backoff.
+ *
+ * @example Basic usage with default settings (2 retries, exponential backoff)
+ * ```ts
+ * import { createAgent, modelRetryMiddleware } from "langchain";
+ *
+ * const agent = createAgent({
+ *   model: "openai:gpt-4o",
+ *   tools: [searchTool],
+ *   middleware: [modelRetryMiddleware()],
+ * });
+ * ```
+ *
+ * @example Retry specific exceptions only
+ * ```ts
+ * import { modelRetryMiddleware } from "langchain";
+ *
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 4,
+ *   retryOn: [TimeoutError, NetworkError],
+ *   backoffFactor: 1.5,
+ * });
+ * ```
+ *
+ * @example Custom exception filtering
+ * ```ts
+ * function shouldRetry(error: Error): boolean {
+ *   // Only retry on rate limit errors
+ *   if (error.name === "RateLimitError") {
+ *     return true;
+ *   }
+ *   // Or check for specific HTTP status codes
+ *   if (error.name === "HTTPError" && "statusCode" in error) {
+ *     const statusCode = (error as any).statusCode;
+ *     return statusCode === 429 || statusCode === 503;
+ *   }
+ *   return false;
+ * }
+ *
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 3,
+ *   retryOn: shouldRetry,
+ * });
+ * ```
+ *
+ * @example Return error message instead of raising
+ * ```ts
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 4,
+ *   onFailure: "continue", // Return AIMessage with error instead of throwing
+ * });
+ * ```
+ *
+ * @example Custom error message formatting
+ * ```ts
+ * const formatError = (error: Error) =>
+ *   `Model call failed: ${error.message}. Please try again later.`;
+ *
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 4,
+ *   onFailure: formatError,
+ * });
+ * ```
+ *
+ * @example Constant backoff (no exponential growth)
+ * ```ts
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 5,
+ *   backoffFactor: 0.0, // No exponential growth
+ *   initialDelayMs: 2000, // Always wait 2 seconds
+ * });
+ * ```
+ *
+ * @example Raise exception on failure
+ * ```ts
+ * const retry = modelRetryMiddleware({
+ *   maxRetries: 2,
+ *   onFailure: "error", // Re-raise exception instead of returning message
+ * });
+ * ```
+ *
+ * @param config - Configuration options for the retry middleware
+ * @returns A middleware instance that handles model failures with retries
+ */
+declare function modelRetryMiddleware(config?: ModelRetryMiddlewareConfig): AgentMiddleware;
+//#endregion
+export { ModelRetryMiddlewareConfig, modelRetryMiddleware };
+//# sourceMappingURL=modelRetry.d.ts.map

package/dist/agents/middleware/modelRetry.js

@@ -0,0 +1,161 @@
+import { calculateRetryDelay, sleep } from "./utils.js";
+import { createMiddleware } from "../middleware.js";
+import { RetrySchema } from "./constants.js";
+import { InvalidRetryConfigError } from "./error.js";
+import { AIMessage } from "@langchain/core/messages";
+import { z } from "zod/v3";
+
+//#region src/agents/middleware/modelRetry.ts
+/**
+* Configuration options for the Model Retry Middleware.
+*/
+const ModelRetryMiddlewareOptionsSchema = z.object({ onFailure: z.union([
+	z.literal("error"),
+	z.literal("continue"),
+	z.function().args(z.instanceof(Error)).returns(z.string())
+]).default("continue") }).merge(RetrySchema);
+/**
+* Middleware that automatically retries failed model calls with configurable backoff.
+*
+* Supports retrying on specific exceptions and exponential backoff.
+*
+* @example Basic usage with default settings (2 retries, exponential backoff)
+* ```ts
+* import { createAgent, modelRetryMiddleware } from "langchain";
+*
+* const agent = createAgent({
+*   model: "openai:gpt-4o",
+*   tools: [searchTool],
+*   middleware: [modelRetryMiddleware()],
+* });
+* ```
+*
+* @example Retry specific exceptions only
+* ```ts
+* import { modelRetryMiddleware } from "langchain";
+*
+* const retry = modelRetryMiddleware({
+*   maxRetries: 4,
+*   retryOn: [TimeoutError, NetworkError],
+*   backoffFactor: 1.5,
+* });
+* ```
+*
+* @example Custom exception filtering
+* ```ts
+* function shouldRetry(error: Error): boolean {
+*   // Only retry on rate limit errors
+*   if (error.name === "RateLimitError") {
+*     return true;
+*   }
+*   // Or check for specific HTTP status codes
+*   if (error.name === "HTTPError" && "statusCode" in error) {
+*     const statusCode = (error as any).statusCode;
+*     return statusCode === 429 || statusCode === 503;
+*   }
+*   return false;
+* }
+*
+* const retry = modelRetryMiddleware({
+*   maxRetries: 3,
+*   retryOn: shouldRetry,
+* });
+* ```
+*
+* @example Return error message instead of raising
+* ```ts
+* const retry = modelRetryMiddleware({
+*   maxRetries: 4,
+*   onFailure: "continue", // Return AIMessage with error instead of throwing
+* });
+* ```
+*
+* @example Custom error message formatting
+* ```ts
+* const formatError = (error: Error) =>
+*   `Model call failed: ${error.message}. Please try again later.`;
+*
+* const retry = modelRetryMiddleware({
+*   maxRetries: 4,
+*   onFailure: formatError,
+* });
+* ```
+*
+* @example Constant backoff (no exponential growth)
+* ```ts
+* const retry = modelRetryMiddleware({
+*   maxRetries: 5,
+*   backoffFactor: 0.0, // No exponential growth
+*   initialDelayMs: 2000, // Always wait 2 seconds
+* });
+* ```
+*
+* @example Raise exception on failure
+* ```ts
+* const retry = modelRetryMiddleware({
+*   maxRetries: 2,
+*   onFailure: "error", // Re-raise exception instead of returning message
+* });
+* ```
+*
+* @param config - Configuration options for the retry middleware
+* @returns A middleware instance that handles model failures with retries
+*/
+function modelRetryMiddleware(config = {}) {
+	const { success, error, data } = ModelRetryMiddlewareOptionsSchema.safeParse(config);
+	if (!success) throw new InvalidRetryConfigError(error);
+	const { maxRetries, retryOn, onFailure, backoffFactor, initialDelayMs, maxDelayMs, jitter } = data;
+	/**
+	* Check if the exception should trigger a retry.
+	*/
+	const shouldRetryException = (error$1) => {
+		if (typeof retryOn === "function") return retryOn(error$1);
+		return retryOn.some((ErrorConstructor) => error$1.constructor === ErrorConstructor);
+	};
+	const delayConfig = {
+		backoffFactor,
+		initialDelayMs,
+		maxDelayMs,
+		jitter
+	};
+	/**
+	* Format the failure message when retries are exhausted.
+	*/
+	const formatFailureMessage = (error$1, attemptsMade) => {
+		const errorType = error$1.constructor.name;
+		const attemptWord = attemptsMade === 1 ? "attempt" : "attempts";
+		return `Model call failed after ${attemptsMade} ${attemptWord} with ${errorType}: ${error$1.message}`;
+	};
+	/**
+	* Handle failure when all retries are exhausted.
+	*/
+	const handleFailure = (error$1, attemptsMade) => {
+		if (onFailure === "error") throw error$1;
+		let content;
+		if (typeof onFailure === "function") content = onFailure(error$1);
+		else content = formatFailureMessage(error$1, attemptsMade);
+		return new AIMessage({ content });
+	};
+	return createMiddleware({
+		name: "modelRetryMiddleware",
+		contextSchema: ModelRetryMiddlewareOptionsSchema,
+		wrapModelCall: async (request, handler) => {
+			for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+				return await handler(request);
+			} catch (error$1) {
+				const attemptsMade = attempt + 1;
+				const err = error$1 && typeof error$1 === "object" && "message" in error$1 ? error$1 : new Error(String(error$1));
+				if (!shouldRetryException(err)) return handleFailure(err, attemptsMade);
+				if (attempt < maxRetries) {
+					const delay = calculateRetryDelay(delayConfig, attempt);
+					if (delay > 0) await sleep(delay);
+				} else return handleFailure(err, attemptsMade);
+			}
+			throw new Error("Unexpected: retry loop completed without returning");
+		}
+	});
+}
+
+//#endregion
+export { modelRetryMiddleware };
+//# sourceMappingURL=modelRetry.js.map