langchain 1.4.6-dev-1781485641139 → 1.4.6

package/dist/agents/middleware/provider/aws/promptCaching.cjs

@@ -0,0 +1,209 @@
+require("../../../../_virtual/_rolldown/runtime.cjs");
+const require_middleware = require("../../../middleware.cjs");
+let zod_v3 = require("zod/v3");
+//#region src/agents/middleware/provider/aws/promptCaching.ts
+const DEFAULT_ENABLE_CACHING = true;
+const DEFAULT_TTL = "5m";
+const DEFAULT_MIN_MESSAGES_TO_CACHE = 1;
+const DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR = "warn";
+const contextSchema = zod_v3.z.object({
+	/**
+	* Whether to enable prompt caching.
+	* @default true
+	*/
+	enableCaching: zod_v3.z.boolean().optional(),
+	/**
+	* The time-to-live for the cached prompt.
+	* @default "5m"
+	*/
+	ttl: zod_v3.z.enum(["5m", "1h"]).optional(),
+	/**
+	* The minimum number of messages required before caching is applied.
+	* @default 1
+	*/
+	minMessagesToCache: zod_v3.z.number().optional(),
+	/**
+	* The behavior to take when an unsupported model is used.
+	* - "ignore" will ignore the unsupported model and continue without caching.
+	* - "warn" will warn the user and continue without caching.
+	* - "raise" will raise an error and stop the agent.
+	* @default "warn"
+	*/
+	unsupportedModelBehavior: zod_v3.z.enum([
+		"ignore",
+		"warn",
+		"raise"
+	]).optional()
+});
+var BedrockPromptCachingMiddlewareError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BedrockPromptCachingMiddlewareError";
+	}
+};
+/**
+* Creates a prompt caching middleware for AWS Bedrock Converse models to optimize API usage.
+*
+* This middleware automatically enables Bedrock's prompt caching when using AWS Bedrock Converse
+* models. This can significantly reduce costs for applications with repetitive prompts, long
+* system messages, or extensive conversation histories.
+*
+* ## How It Works
+*
+* The middleware intercepts model requests and sets a cache control signal that
+* `ChatBedrockConverse` translates into Bedrock `cachePoint` breakpoints. Cache points are
+* inserted after the system prompt, after the tool definitions, and after the final message, so
+* the stable prefix of each request is cached. On subsequent requests with a matching prefix, the
+* cached representations are reused, skipping redundant token processing. Exact placement varies
+* by model (e.g. Amazon Nova models cache fewer breakpoints and ignore the `"1h"` TTL).
+*
+* ## Benefits
+*
+* - **Cost Reduction**: Avoid reprocessing the same tokens repeatedly
+* - **Lower Latency**: Cached prompts are processed faster as embeddings are pre-computed
+* - **Better Scalability**: Reduced computational load enables handling more requests
+* - **Consistent Performance**: Stable response times for repetitive queries
+*
+* @param middlewareOptions - Configuration options for the caching behavior
+* @param middlewareOptions.enableCaching - Whether to enable prompt caching (default: `true`)
+* @param middlewareOptions.ttl - Cache time-to-live: `"5m"` for 5 minutes or `"1h"` for 1 hour (default: `"5m"`)
+* @param middlewareOptions.minMessagesToCache - Minimum number of messages required before caching is applied (default: `1`)
+* @param middlewareOptions.unsupportedModelBehavior - The behavior to take when an unsupported model is used (default: `"warn"`)
+*
+* @returns A middleware instance that can be passed to `createAgent`
+*
+* @throws {Error} When `unsupportedModelBehavior` is `"raise"` and the model is not a
+* cache-capable Bedrock Converse model — either a non-Bedrock provider, or a Bedrock
+* Converse model outside the Anthropic Claude / Amazon Nova families.
+*
+* @example
+* Basic usage with default settings
+* ```typescript
+* import { createAgent } from "langchain";
+* import { bedrockPromptCachingMiddleware } from "langchain";
+*
+* const agent = createAgent({
+*   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+*   middleware: [
+*     bedrockPromptCachingMiddleware()
+*   ]
+* });
+* ```
+*
+* @example
+* Custom configuration for longer conversations
+* ```typescript
+* const cachingMiddleware = bedrockPromptCachingMiddleware({
+*   ttl: "1h",  // Cache for 1 hour instead of default 5 minutes
+*   minMessagesToCache: 5  // Only cache after 5 messages
+* });
+*
+* const agent = createAgent({
+*   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+*   systemPrompt: "You are a helpful assistant with deep knowledge of...", // Long system prompt
+*   middleware: [cachingMiddleware]
+* });
+* ```
+*
+* @example
+* Conditional caching based on runtime context
+* ```typescript
+* const agent = createAgent({
+*   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+*   middleware: [
+*     bedrockPromptCachingMiddleware({
+*       enableCaching: true,
+*       ttl: "5m"
+*     })
+*   ]
+* });
+*
+* // Disable caching for specific requests
+* await agent.invoke(
+*   { messages: [new HumanMessage("Process this without caching")] },
+*   {
+*     configurable: {
+*       middleware_context: { enableCaching: false }
+*     }
+*   }
+* );
+* ```
+*
+* @example
+* Optimal setup for customer support chatbot
+* ```typescript
+* const supportAgent = createAgent({
+*   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+*   systemPrompt: `You are a customer support agent for ACME Corp.
+*
+*     Company policies:
+*     - Always be polite and professional
+*     - Refer to knowledge base for product information
+*     - Escalate billing issues to human agents
+*     ... (extensive policies and guidelines)
+*   `,
+*   tools: [searchKnowledgeBase, createTicket, checkOrderStatus],
+*   middleware: [
+*     bedrockPromptCachingMiddleware({
+*       ttl: "1h",  // Long TTL for stable system prompt
+*       minMessagesToCache: 1  // Cache immediately due to large system prompt
+*     })
+*   ]
+* });
+* ```
+*
+* @remarks
+* - **Bedrock Converse Only**: This middleware only applies caching to AWS Bedrock Converse models. Other providers are handled per `unsupportedModelBehavior`
+* - **Supported Families**: Bedrock prompt caching is only available on the **Anthropic Claude** and **Amazon Nova** model families. Other Bedrock Converse models (e.g. Mistral, Cohere, Meta) reject cache points at request time, so they are treated as unsupported and routed through `unsupportedModelBehavior`
+* - **Automatic Application**: Caching is applied automatically when the message count reaches `minMessagesToCache`
+* - **TTL Options**: Only supports "5m" (5 minutes) and "1h" (1 hour) as TTL values; actual support varies by model
+* - **Best Use Cases**: Long system prompts, multi-turn conversations, repetitive queries, RAG applications
+*
+* @see {@link createAgent} for agent creation
+* @see {@link https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html} AWS Bedrock prompt caching documentation
+* @public
+*/
+function bedrockPromptCachingMiddleware(middlewareOptions) {
+	return require_middleware.createMiddleware({
+		name: "BedrockPromptCachingMiddleware",
+		contextSchema,
+		wrapModelCall: (request, handler) => {
+			const enableCaching = request.runtime.context.enableCaching ?? middlewareOptions?.enableCaching ?? DEFAULT_ENABLE_CACHING;
+			const ttl = request.runtime.context.ttl ?? middlewareOptions?.ttl ?? DEFAULT_TTL;
+			const minMessagesToCache = request.runtime.context.minMessagesToCache ?? middlewareOptions?.minMessagesToCache ?? DEFAULT_MIN_MESSAGES_TO_CACHE;
+			const unsupportedModelBehavior = request.runtime.context.unsupportedModelBehavior ?? middlewareOptions?.unsupportedModelBehavior ?? DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR;
+			if (!enableCaching || !request.model) return handler(request);
+			const modelName = request.model.getName();
+			const isBedrockConverseModel = modelName === "ChatBedrockConverse" || modelName === "ConfigurableModel" && (request.model._defaultConfig?.modelProvider === "bedrock" || request.model._defaultConfig?.modelProvider === "aws");
+			const modelId = modelName === "ConfigurableModel" ? request.model._defaultConfig?.model : request.model.model;
+			if (!(isBedrockConverseModel && typeof modelId === "string" && (modelId.toLowerCase().includes("anthropic.claude") || modelId.toLowerCase().includes("amazon.nova")))) {
+				const modelInfo = modelName === "ConfigurableModel" ? `${modelName} (${request.model._defaultConfig?.modelProvider})` : modelName;
+				const baseMessage = isBedrockConverseModel ? `Unsupported model '${modelInfo}'. Bedrock prompt caching is only supported on Anthropic Claude and Amazon Nova models` : `Unsupported model '${modelInfo}'. Prompt caching requires an AWS Bedrock Converse model`;
+				if (unsupportedModelBehavior === "raise") throw new BedrockPromptCachingMiddlewareError(`${baseMessage} (e.g., 'bedrock:anthropic.claude-haiku-4-5-20251001-v1:0').`);
+				else if (unsupportedModelBehavior === "warn") console.warn(`BedrockPromptCachingMiddleware: Skipping caching for ${modelName}. Consider switching to an Anthropic Claude or Amazon Nova model for caching benefits.`);
+				return handler(request);
+			}
+			if (request.state.messages.length + (request.systemPrompt ? 1 : 0) < minMessagesToCache) return handler(request);
+			/**
+			* The cache_control is applied at the final message formatting layer in
+			* ChatBedrockConverse (translated into Converse `cachePoint` blocks).
+			*
+			* @see https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
+			*/
+			return handler({
+				...request,
+				modelSettings: {
+					...request.modelSettings,
+					cache_control: {
+						type: "ephemeral",
+						ttl
+					}
+				}
+			});
+		}
+	});
+}
+//#endregion
+exports.bedrockPromptCachingMiddleware = bedrockPromptCachingMiddleware;
+
+//# sourceMappingURL=promptCaching.cjs.map

package/dist/agents/middleware/provider/aws/promptCaching.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptCaching.cjs","names":["z","createMiddleware"],"sources":["../../../../../src/agents/middleware/provider/aws/promptCaching.ts"],"sourcesContent":["import { z } from \"zod/v3\";\nimport { InferInteropZodInput } from \"@langchain/core/utils/types\";\n\nimport type { ConfigurableModel } from \"../../../../chat_models/universal.js\";\nimport { createMiddleware } from \"../../../middleware.js\";\n\nconst DEFAULT_ENABLE_CACHING = true;\nconst DEFAULT_TTL = \"5m\";\nconst DEFAULT_MIN_MESSAGES_TO_CACHE = 1;\nconst DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR = \"warn\";\n\nconst contextSchema = z.object({\n  /**\n   * Whether to enable prompt caching.\n   * @default true\n   */\n  enableCaching: z.boolean().optional(),\n  /**\n   * The time-to-live for the cached prompt.\n   * @default \"5m\"\n   */\n  ttl: z.enum([\"5m\", \"1h\"]).optional(),\n  /**\n   * The minimum number of messages required before caching is applied.\n   * @default 1\n   */\n  minMessagesToCache: z.number().optional(),\n  /**\n   * The behavior to take when an unsupported model is used.\n   * - \"ignore\" will ignore the unsupported model and continue without caching.\n   * - \"warn\" will warn the user and continue without caching.\n   * - \"raise\" will raise an error and stop the agent.\n   * @default \"warn\"\n   */\n  unsupportedModelBehavior: z.enum([\"ignore\", \"warn\", \"raise\"]).optional(),\n});\nexport type BedrockConversePromptCachingMiddlewareConfig = Partial<\n  InferInteropZodInput<typeof contextSchema>\n>;\n\nclass BedrockPromptCachingMiddlewareError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"BedrockPromptCachingMiddlewareError\";\n  }\n}\n\n/**\n * Creates a prompt caching middleware for AWS Bedrock Converse models to optimize API usage.\n *\n * This middleware automatically enables Bedrock's prompt caching when using AWS Bedrock Converse\n * models. This can significantly reduce costs for applications with repetitive prompts, long\n * system messages, or extensive conversation histories.\n *\n * ## How It Works\n *\n * The middleware intercepts model requests and sets a cache control signal that\n * `ChatBedrockConverse` translates into Bedrock `cachePoint` breakpoints. Cache points are\n * inserted after the system prompt, after the tool definitions, and after the final message, so\n * the stable prefix of each request is cached. On subsequent requests with a matching prefix, the\n * cached representations are reused, skipping redundant token processing. Exact placement varies\n * by model (e.g. Amazon Nova models cache fewer breakpoints and ignore the `\"1h\"` TTL).\n *\n * ## Benefits\n *\n * - **Cost Reduction**: Avoid reprocessing the same tokens repeatedly\n * - **Lower Latency**: Cached prompts are processed faster as embeddings are pre-computed\n * - **Better Scalability**: Reduced computational load enables handling more requests\n * - **Consistent Performance**: Stable response times for repetitive queries\n *\n * @param middlewareOptions - Configuration options for the caching behavior\n * @param middlewareOptions.enableCaching - Whether to enable prompt caching (default: `true`)\n * @param middlewareOptions.ttl - Cache time-to-live: `\"5m\"` for 5 minutes or `\"1h\"` for 1 hour (default: `\"5m\"`)\n * @param middlewareOptions.minMessagesToCache - Minimum number of messages required before caching is applied (default: `1`)\n * @param middlewareOptions.unsupportedModelBehavior - The behavior to take when an unsupported model is used (default: `\"warn\"`)\n *\n * @returns A middleware instance that can be passed to `createAgent`\n *\n * @throws {Error} When `unsupportedModelBehavior` is `\"raise\"` and the model is not a\n * cache-capable Bedrock Converse model — either a non-Bedrock provider, or a Bedrock\n * Converse model outside the Anthropic Claude / Amazon Nova families.\n *\n * @example\n * Basic usage with default settings\n * ```typescript\n * import { createAgent } from \"langchain\";\n * import { bedrockPromptCachingMiddleware } from \"langchain\";\n *\n * const agent = createAgent({\n *   model: \"bedrock:anthropic.claude-haiku-4-5-20251001-v1:0\",\n *   middleware: [\n *     bedrockPromptCachingMiddleware()\n *   ]\n * });\n * ```\n *\n * @example\n * Custom configuration for longer conversations\n * ```typescript\n * const cachingMiddleware = bedrockPromptCachingMiddleware({\n *   ttl: \"1h\",  // Cache for 1 hour instead of default 5 minutes\n *   minMessagesToCache: 5  // Only cache after 5 messages\n * });\n *\n * const agent = createAgent({\n *   model: \"bedrock:anthropic.claude-haiku-4-5-20251001-v1:0\",\n *   systemPrompt: \"You are a helpful assistant with deep knowledge of...\", // Long system prompt\n *   middleware: [cachingMiddleware]\n * });\n * ```\n *\n * @example\n * Conditional caching based on runtime context\n * ```typescript\n * const agent = createAgent({\n *   model: \"bedrock:anthropic.claude-haiku-4-5-20251001-v1:0\",\n *   middleware: [\n *     bedrockPromptCachingMiddleware({\n *       enableCaching: true,\n *       ttl: \"5m\"\n *     })\n *   ]\n * });\n *\n * // Disable caching for specific requests\n * await agent.invoke(\n *   { messages: [new HumanMessage(\"Process this without caching\")] },\n *   {\n *     configurable: {\n *       middleware_context: { enableCaching: false }\n *     }\n *   }\n * );\n * ```\n *\n * @example\n * Optimal setup for customer support chatbot\n * ```typescript\n * const supportAgent = createAgent({\n *   model: \"bedrock:anthropic.claude-haiku-4-5-20251001-v1:0\",\n *   systemPrompt: `You are a customer support agent for ACME Corp.\n *\n *     Company policies:\n *     - Always be polite and professional\n *     - Refer to knowledge base for product information\n *     - Escalate billing issues to human agents\n *     ... (extensive policies and guidelines)\n *   `,\n *   tools: [searchKnowledgeBase, createTicket, checkOrderStatus],\n *   middleware: [\n *     bedrockPromptCachingMiddleware({\n *       ttl: \"1h\",  // Long TTL for stable system prompt\n *       minMessagesToCache: 1  // Cache immediately due to large system prompt\n *     })\n *   ]\n * });\n * ```\n *\n * @remarks\n * - **Bedrock Converse Only**: This middleware only applies caching to AWS Bedrock Converse models. Other providers are handled per `unsupportedModelBehavior`\n * - **Supported Families**: Bedrock prompt caching is only available on the **Anthropic Claude** and **Amazon Nova** model families. Other Bedrock Converse models (e.g. Mistral, Cohere, Meta) reject cache points at request time, so they are treated as unsupported and routed through `unsupportedModelBehavior`\n * - **Automatic Application**: Caching is applied automatically when the message count reaches `minMessagesToCache`\n * - **TTL Options**: Only supports \"5m\" (5 minutes) and \"1h\" (1 hour) as TTL values; actual support varies by model\n * - **Best Use Cases**: Long system prompts, multi-turn conversations, repetitive queries, RAG applications\n *\n * @see {@link createAgent} for agent creation\n * @see {@link https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html} AWS Bedrock prompt caching documentation\n * @public\n */\nexport function bedrockPromptCachingMiddleware(\n  middlewareOptions?: BedrockConversePromptCachingMiddlewareConfig\n) {\n  return createMiddleware({\n    name: \"BedrockPromptCachingMiddleware\",\n    contextSchema,\n    wrapModelCall: (request, handler) => {\n      const enableCaching =\n        request.runtime.context.enableCaching ??\n        middlewareOptions?.enableCaching ??\n        DEFAULT_ENABLE_CACHING;\n      const ttl =\n        request.runtime.context.ttl ?? middlewareOptions?.ttl ?? DEFAULT_TTL;\n      const minMessagesToCache =\n        request.runtime.context.minMessagesToCache ??\n        middlewareOptions?.minMessagesToCache ??\n        DEFAULT_MIN_MESSAGES_TO_CACHE;\n      const unsupportedModelBehavior =\n        request.runtime.context.unsupportedModelBehavior ??\n        middlewareOptions?.unsupportedModelBehavior ??\n        DEFAULT_UNSUPPORTED_MODEL_BEHAVIOR;\n\n      // Skip if caching is disabled\n      if (!enableCaching || !request.model) {\n        return handler(request);\n      }\n\n      const modelName = request.model.getName();\n      const isBedrockConverseModel =\n        modelName === \"ChatBedrockConverse\" ||\n        (modelName === \"ConfigurableModel\" &&\n          ((request.model as ConfigurableModel)._defaultConfig\n            ?.modelProvider === \"bedrock\" ||\n            (request.model as ConfigurableModel)._defaultConfig\n              ?.modelProvider === \"aws\"));\n\n      // Resolve the underlying Bedrock model id for cache-capability detection.\n      const modelId =\n        modelName === \"ConfigurableModel\"\n          ? ((request.model as ConfigurableModel)._defaultConfig?.model as\n              | string\n              | undefined)\n          : (request.model as { model?: string }).model;\n\n      // Bedrock prompt caching is only supported on the Anthropic Claude and\n      // Amazon Nova model families. Other Converse models (Mistral, Cohere,\n      // Meta, etc.) reject `cachePoint` blocks with an AccessDeniedException, so\n      // they are treated as unsupported.\n      const isCacheCapableModel =\n        isBedrockConverseModel &&\n        typeof modelId === \"string\" &&\n        (modelId.toLowerCase().includes(\"anthropic.claude\") ||\n          modelId.toLowerCase().includes(\"amazon.nova\"));\n\n      if (!isCacheCapableModel) {\n        const modelInfo =\n          modelName === \"ConfigurableModel\"\n            ? `${modelName} (${\n                (request.model as ConfigurableModel)._defaultConfig\n                  ?.modelProvider\n              })`\n            : modelName;\n\n        const baseMessage = isBedrockConverseModel\n          ? `Unsupported model '${modelInfo}'. Bedrock prompt caching is only supported on Anthropic Claude and Amazon Nova models`\n          : `Unsupported model '${modelInfo}'. Prompt caching requires an AWS Bedrock Converse model`;\n\n        if (unsupportedModelBehavior === \"raise\") {\n          throw new BedrockPromptCachingMiddlewareError(\n            `${baseMessage} (e.g., 'bedrock:anthropic.claude-haiku-4-5-20251001-v1:0').`\n          );\n        } else if (unsupportedModelBehavior === \"warn\") {\n          console.warn(\n            `BedrockPromptCachingMiddleware: Skipping caching for ${modelName}. Consider switching to an Anthropic Claude or Amazon Nova model for caching benefits.`\n          );\n        }\n        return handler(request);\n      }\n\n      const messagesCount =\n        request.state.messages.length + (request.systemPrompt ? 1 : 0);\n\n      if (messagesCount < minMessagesToCache) {\n        return handler(request);\n      }\n\n      /**\n       * The cache_control is applied at the final message formatting layer in\n       * ChatBedrockConverse (translated into Converse `cachePoint` blocks).\n       *\n       * @see https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html\n       */\n      return handler({\n        ...request,\n        modelSettings: {\n          ...request.modelSettings,\n          cache_control: {\n            type: \"ephemeral\" as const,\n            ttl,\n          },\n        },\n      });\n    },\n  });\n}\n"],"mappings":";;;;AAMA,MAAM,yBAAyB;AAC/B,MAAM,cAAc;AACpB,MAAM,gCAAgC;AACtC,MAAM,qCAAqC;AAE3C,MAAM,gBAAgBA,OAAAA,EAAE,OAAO;;;;;CAK7B,eAAeA,OAAAA,EAAE,SAAS,CAAC,UAAU;;;;;CAKrC,KAAKA,OAAAA,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,UAAU;;;;;CAKpC,oBAAoBA,OAAAA,EAAE,QAAQ,CAAC,UAAU;;;;;;;;CAQzC,0BAA0BA,OAAAA,EAAE,KAAK;EAAC;EAAU;EAAQ;EAAQ,CAAC,CAAC,UAAU;CACzE,CAAC;AAKF,IAAM,sCAAN,cAAkD,MAAM;CACtD,YAAY,SAAiB;AAC3B,QAAM,QAAQ;AACd,OAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8HhB,SAAgB,+BACd,mBACA;AACA,QAAOC,mBAAAA,iBAAiB;EACtB,MAAM;EACN;EACA,gBAAgB,SAAS,YAAY;GACnC,MAAM,gBACJ,QAAQ,QAAQ,QAAQ,iBACxB,mBAAmB,iBACnB;GACF,MAAM,MACJ,QAAQ,QAAQ,QAAQ,OAAO,mBAAmB,OAAO;GAC3D,MAAM,qBACJ,QAAQ,QAAQ,QAAQ,sBACxB,mBAAmB,sBACnB;GACF,MAAM,2BACJ,QAAQ,QAAQ,QAAQ,4BACxB,mBAAmB,4BACnB;AAGF,OAAI,CAAC,iBAAiB,CAAC,QAAQ,MAC7B,QAAO,QAAQ,QAAQ;GAGzB,MAAM,YAAY,QAAQ,MAAM,SAAS;GACzC,MAAM,yBACJ,cAAc,yBACb,cAAc,wBACX,QAAQ,MAA4B,gBAClC,kBAAkB,aACnB,QAAQ,MAA4B,gBACjC,kBAAkB;GAG5B,MAAM,UACJ,cAAc,sBACR,QAAQ,MAA4B,gBAAgB,QAGrD,QAAQ,MAA6B;AAY5C,OAAI,EALF,0BACA,OAAO,YAAY,aAClB,QAAQ,aAAa,CAAC,SAAS,mBAAmB,IACjD,QAAQ,aAAa,CAAC,SAAS,cAAc,IAEvB;IACxB,MAAM,YACJ,cAAc,sBACV,GAAG,UAAU,IACV,QAAQ,MAA4B,gBACjC,cACL,KACD;IAEN,MAAM,cAAc,yBAChB,sBAAsB,UAAU,0FAChC,sBAAsB,UAAU;AAEpC,QAAI,6BAA6B,QAC/B,OAAM,IAAI,oCACR,GAAG,YAAY,8DAChB;aACQ,6BAA6B,OACtC,SAAQ,KACN,wDAAwD,UAAU,wFACnE;AAEH,WAAO,QAAQ,QAAQ;;AAMzB,OAFE,QAAQ,MAAM,SAAS,UAAU,QAAQ,eAAe,IAAI,KAE1C,mBAClB,QAAO,QAAQ,QAAQ;;;;;;;AASzB,UAAO,QAAQ;IACb,GAAG;IACH,eAAe;KACb,GAAG,QAAQ;KACX,eAAe;MACb,MAAM;MACN;MACD;KACF;IACF,CAAC;;EAEL,CAAC"}

package/dist/agents/middleware/provider/aws/promptCaching.d.cts

@@ -0,0 +1,207 @@
+import { AgentMiddleware } from "../../types.cjs";
+import * as _$_langchain_core_tools0 from "@langchain/core/tools";
+import { InferInteropZodInput } from "@langchain/core/utils/types";
+import { z } from "zod/v3";
+
+//#region src/agents/middleware/provider/aws/promptCaching.d.ts
+declare const contextSchema: z.ZodObject<{
+  /**
+   * Whether to enable prompt caching.
+   * @default true
+   */
+  enableCaching: z.ZodOptional<z.ZodBoolean>;
+  /**
+   * The time-to-live for the cached prompt.
+   * @default "5m"
+   */
+  ttl: z.ZodOptional<z.ZodEnum<["5m", "1h"]>>;
+  /**
+   * The minimum number of messages required before caching is applied.
+   * @default 1
+   */
+  minMessagesToCache: z.ZodOptional<z.ZodNumber>;
+  /**
+   * The behavior to take when an unsupported model is used.
+   * - "ignore" will ignore the unsupported model and continue without caching.
+   * - "warn" will warn the user and continue without caching.
+   * - "raise" will raise an error and stop the agent.
+   * @default "warn"
+   */
+  unsupportedModelBehavior: z.ZodOptional<z.ZodEnum<["ignore", "warn", "raise"]>>;
+}, "strip", z.ZodTypeAny, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}>;
+type BedrockConversePromptCachingMiddlewareConfig = Partial<InferInteropZodInput<typeof contextSchema>>;
+/**
+ * Creates a prompt caching middleware for AWS Bedrock Converse models to optimize API usage.
+ *
+ * This middleware automatically enables Bedrock's prompt caching when using AWS Bedrock Converse
+ * models. This can significantly reduce costs for applications with repetitive prompts, long
+ * system messages, or extensive conversation histories.
+ *
+ * ## How It Works
+ *
+ * The middleware intercepts model requests and sets a cache control signal that
+ * `ChatBedrockConverse` translates into Bedrock `cachePoint` breakpoints. Cache points are
+ * inserted after the system prompt, after the tool definitions, and after the final message, so
+ * the stable prefix of each request is cached. On subsequent requests with a matching prefix, the
+ * cached representations are reused, skipping redundant token processing. Exact placement varies
+ * by model (e.g. Amazon Nova models cache fewer breakpoints and ignore the `"1h"` TTL).
+ *
+ * ## Benefits
+ *
+ * - **Cost Reduction**: Avoid reprocessing the same tokens repeatedly
+ * - **Lower Latency**: Cached prompts are processed faster as embeddings are pre-computed
+ * - **Better Scalability**: Reduced computational load enables handling more requests
+ * - **Consistent Performance**: Stable response times for repetitive queries
+ *
+ * @param middlewareOptions - Configuration options for the caching behavior
+ * @param middlewareOptions.enableCaching - Whether to enable prompt caching (default: `true`)
+ * @param middlewareOptions.ttl - Cache time-to-live: `"5m"` for 5 minutes or `"1h"` for 1 hour (default: `"5m"`)
+ * @param middlewareOptions.minMessagesToCache - Minimum number of messages required before caching is applied (default: `1`)
+ * @param middlewareOptions.unsupportedModelBehavior - The behavior to take when an unsupported model is used (default: `"warn"`)
+ *
+ * @returns A middleware instance that can be passed to `createAgent`
+ *
+ * @throws {Error} When `unsupportedModelBehavior` is `"raise"` and the model is not a
+ * cache-capable Bedrock Converse model — either a non-Bedrock provider, or a Bedrock
+ * Converse model outside the Anthropic Claude / Amazon Nova families.
+ *
+ * @example
+ * Basic usage with default settings
+ * ```typescript
+ * import { createAgent } from "langchain";
+ * import { bedrockPromptCachingMiddleware } from "langchain";
+ *
+ * const agent = createAgent({
+ *   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+ *   middleware: [
+ *     bedrockPromptCachingMiddleware()
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * Custom configuration for longer conversations
+ * ```typescript
+ * const cachingMiddleware = bedrockPromptCachingMiddleware({
+ *   ttl: "1h",  // Cache for 1 hour instead of default 5 minutes
+ *   minMessagesToCache: 5  // Only cache after 5 messages
+ * });
+ *
+ * const agent = createAgent({
+ *   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+ *   systemPrompt: "You are a helpful assistant with deep knowledge of...", // Long system prompt
+ *   middleware: [cachingMiddleware]
+ * });
+ * ```
+ *
+ * @example
+ * Conditional caching based on runtime context
+ * ```typescript
+ * const agent = createAgent({
+ *   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+ *   middleware: [
+ *     bedrockPromptCachingMiddleware({
+ *       enableCaching: true,
+ *       ttl: "5m"
+ *     })
+ *   ]
+ * });
+ *
+ * // Disable caching for specific requests
+ * await agent.invoke(
+ *   { messages: [new HumanMessage("Process this without caching")] },
+ *   {
+ *     configurable: {
+ *       middleware_context: { enableCaching: false }
+ *     }
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * Optimal setup for customer support chatbot
+ * ```typescript
+ * const supportAgent = createAgent({
+ *   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+ *   systemPrompt: `You are a customer support agent for ACME Corp.
+ *
+ *     Company policies:
+ *     - Always be polite and professional
+ *     - Refer to knowledge base for product information
+ *     - Escalate billing issues to human agents
+ *     ... (extensive policies and guidelines)
+ *   `,
+ *   tools: [searchKnowledgeBase, createTicket, checkOrderStatus],
+ *   middleware: [
+ *     bedrockPromptCachingMiddleware({
+ *       ttl: "1h",  // Long TTL for stable system prompt
+ *       minMessagesToCache: 1  // Cache immediately due to large system prompt
+ *     })
+ *   ]
+ * });
+ * ```
+ *
+ * @remarks
+ * - **Bedrock Converse Only**: This middleware only applies caching to AWS Bedrock Converse models. Other providers are handled per `unsupportedModelBehavior`
+ * - **Supported Families**: Bedrock prompt caching is only available on the **Anthropic Claude** and **Amazon Nova** model families. Other Bedrock Converse models (e.g. Mistral, Cohere, Meta) reject cache points at request time, so they are treated as unsupported and routed through `unsupportedModelBehavior`
+ * - **Automatic Application**: Caching is applied automatically when the message count reaches `minMessagesToCache`
+ * - **TTL Options**: Only supports "5m" (5 minutes) and "1h" (1 hour) as TTL values; actual support varies by model
+ * - **Best Use Cases**: Long system prompts, multi-turn conversations, repetitive queries, RAG applications
+ *
+ * @see {@link createAgent} for agent creation
+ * @see {@link https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html} AWS Bedrock prompt caching documentation
+ * @public
+ */
+declare function bedrockPromptCachingMiddleware(middlewareOptions?: BedrockConversePromptCachingMiddlewareConfig): AgentMiddleware<undefined, z.ZodObject<{
+  /**
+   * Whether to enable prompt caching.
+   * @default true
+   */
+  enableCaching: z.ZodOptional<z.ZodBoolean>;
+  /**
+   * The time-to-live for the cached prompt.
+   * @default "5m"
+   */
+  ttl: z.ZodOptional<z.ZodEnum<["5m", "1h"]>>;
+  /**
+   * The minimum number of messages required before caching is applied.
+   * @default 1
+   */
+  minMessagesToCache: z.ZodOptional<z.ZodNumber>;
+  /**
+   * The behavior to take when an unsupported model is used.
+   * - "ignore" will ignore the unsupported model and continue without caching.
+   * - "warn" will warn the user and continue without caching.
+   * - "raise" will raise an error and stop the agent.
+   * @default "warn"
+   */
+  unsupportedModelBehavior: z.ZodOptional<z.ZodEnum<["ignore", "warn", "raise"]>>;
+}, "strip", z.ZodTypeAny, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}>, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}, readonly (_$_langchain_core_tools0.ServerTool | _$_langchain_core_tools0.ClientTool)[], readonly []>;
+//#endregion
+export { BedrockConversePromptCachingMiddlewareConfig, bedrockPromptCachingMiddleware };
+//# sourceMappingURL=promptCaching.d.cts.map

package/dist/agents/middleware/provider/aws/promptCaching.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptCaching.d.cts","names":[],"sources":["../../../../../src/agents/middleware/provider/aws/promptCaching.ts"],"mappings":";;;;;;cAWM,aAAA,EAAa,CAAA,CAAA,SAAA;;;;AAVgD;;;;;;;;;;;;EAUhD;;;;;;;;;;;;;;;;;;;KAyBP,4CAAA,GAA+C,OAAA,CACzD,oBAAA,QAA4B,aAAA;;;;;;;;;;;;;;;;;;AAD9B;;;;;;;;;;;;;AAqIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,8BAAA,CACd,iBAAA,GAAoB,4CAAA,8BAA4C,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAAA,wBAAA,CAAA,UAAA"}

package/dist/agents/middleware/provider/aws/promptCaching.d.ts

@@ -0,0 +1,207 @@
+import { AgentMiddleware } from "../../types.js";
+import * as _$_langchain_core_tools0 from "@langchain/core/tools";
+import { InferInteropZodInput } from "@langchain/core/utils/types";
+import { z } from "zod/v3";
+
+//#region src/agents/middleware/provider/aws/promptCaching.d.ts
+declare const contextSchema: z.ZodObject<{
+  /**
+   * Whether to enable prompt caching.
+   * @default true
+   */
+  enableCaching: z.ZodOptional<z.ZodBoolean>;
+  /**
+   * The time-to-live for the cached prompt.
+   * @default "5m"
+   */
+  ttl: z.ZodOptional<z.ZodEnum<["5m", "1h"]>>;
+  /**
+   * The minimum number of messages required before caching is applied.
+   * @default 1
+   */
+  minMessagesToCache: z.ZodOptional<z.ZodNumber>;
+  /**
+   * The behavior to take when an unsupported model is used.
+   * - "ignore" will ignore the unsupported model and continue without caching.
+   * - "warn" will warn the user and continue without caching.
+   * - "raise" will raise an error and stop the agent.
+   * @default "warn"
+   */
+  unsupportedModelBehavior: z.ZodOptional<z.ZodEnum<["ignore", "warn", "raise"]>>;
+}, "strip", z.ZodTypeAny, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}>;
+type BedrockConversePromptCachingMiddlewareConfig = Partial<InferInteropZodInput<typeof contextSchema>>;
+/**
+ * Creates a prompt caching middleware for AWS Bedrock Converse models to optimize API usage.
+ *
+ * This middleware automatically enables Bedrock's prompt caching when using AWS Bedrock Converse
+ * models. This can significantly reduce costs for applications with repetitive prompts, long
+ * system messages, or extensive conversation histories.
+ *
+ * ## How It Works
+ *
+ * The middleware intercepts model requests and sets a cache control signal that
+ * `ChatBedrockConverse` translates into Bedrock `cachePoint` breakpoints. Cache points are
+ * inserted after the system prompt, after the tool definitions, and after the final message, so
+ * the stable prefix of each request is cached. On subsequent requests with a matching prefix, the
+ * cached representations are reused, skipping redundant token processing. Exact placement varies
+ * by model (e.g. Amazon Nova models cache fewer breakpoints and ignore the `"1h"` TTL).
+ *
+ * ## Benefits
+ *
+ * - **Cost Reduction**: Avoid reprocessing the same tokens repeatedly
+ * - **Lower Latency**: Cached prompts are processed faster as embeddings are pre-computed
+ * - **Better Scalability**: Reduced computational load enables handling more requests
+ * - **Consistent Performance**: Stable response times for repetitive queries
+ *
+ * @param middlewareOptions - Configuration options for the caching behavior
+ * @param middlewareOptions.enableCaching - Whether to enable prompt caching (default: `true`)
+ * @param middlewareOptions.ttl - Cache time-to-live: `"5m"` for 5 minutes or `"1h"` for 1 hour (default: `"5m"`)
+ * @param middlewareOptions.minMessagesToCache - Minimum number of messages required before caching is applied (default: `1`)
+ * @param middlewareOptions.unsupportedModelBehavior - The behavior to take when an unsupported model is used (default: `"warn"`)
+ *
+ * @returns A middleware instance that can be passed to `createAgent`
+ *
+ * @throws {Error} When `unsupportedModelBehavior` is `"raise"` and the model is not a
+ * cache-capable Bedrock Converse model — either a non-Bedrock provider, or a Bedrock
+ * Converse model outside the Anthropic Claude / Amazon Nova families.
+ *
+ * @example
+ * Basic usage with default settings
+ * ```typescript
+ * import { createAgent } from "langchain";
+ * import { bedrockPromptCachingMiddleware } from "langchain";
+ *
+ * const agent = createAgent({
+ *   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+ *   middleware: [
+ *     bedrockPromptCachingMiddleware()
+ *   ]
+ * });
+ * ```
+ *
+ * @example
+ * Custom configuration for longer conversations
+ * ```typescript
+ * const cachingMiddleware = bedrockPromptCachingMiddleware({
+ *   ttl: "1h",  // Cache for 1 hour instead of default 5 minutes
+ *   minMessagesToCache: 5  // Only cache after 5 messages
+ * });
+ *
+ * const agent = createAgent({
+ *   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+ *   systemPrompt: "You are a helpful assistant with deep knowledge of...", // Long system prompt
+ *   middleware: [cachingMiddleware]
+ * });
+ * ```
+ *
+ * @example
+ * Conditional caching based on runtime context
+ * ```typescript
+ * const agent = createAgent({
+ *   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+ *   middleware: [
+ *     bedrockPromptCachingMiddleware({
+ *       enableCaching: true,
+ *       ttl: "5m"
+ *     })
+ *   ]
+ * });
+ *
+ * // Disable caching for specific requests
+ * await agent.invoke(
+ *   { messages: [new HumanMessage("Process this without caching")] },
+ *   {
+ *     configurable: {
+ *       middleware_context: { enableCaching: false }
+ *     }
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * Optimal setup for customer support chatbot
+ * ```typescript
+ * const supportAgent = createAgent({
+ *   model: "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
+ *   systemPrompt: `You are a customer support agent for ACME Corp.
+ *
+ *     Company policies:
+ *     - Always be polite and professional
+ *     - Refer to knowledge base for product information
+ *     - Escalate billing issues to human agents
+ *     ... (extensive policies and guidelines)
+ *   `,
+ *   tools: [searchKnowledgeBase, createTicket, checkOrderStatus],
+ *   middleware: [
+ *     bedrockPromptCachingMiddleware({
+ *       ttl: "1h",  // Long TTL for stable system prompt
+ *       minMessagesToCache: 1  // Cache immediately due to large system prompt
+ *     })
+ *   ]
+ * });
+ * ```
+ *
+ * @remarks
+ * - **Bedrock Converse Only**: This middleware only applies caching to AWS Bedrock Converse models. Other providers are handled per `unsupportedModelBehavior`
+ * - **Supported Families**: Bedrock prompt caching is only available on the **Anthropic Claude** and **Amazon Nova** model families. Other Bedrock Converse models (e.g. Mistral, Cohere, Meta) reject cache points at request time, so they are treated as unsupported and routed through `unsupportedModelBehavior`
+ * - **Automatic Application**: Caching is applied automatically when the message count reaches `minMessagesToCache`
+ * - **TTL Options**: Only supports "5m" (5 minutes) and "1h" (1 hour) as TTL values; actual support varies by model
+ * - **Best Use Cases**: Long system prompts, multi-turn conversations, repetitive queries, RAG applications
+ *
+ * @see {@link createAgent} for agent creation
+ * @see {@link https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html} AWS Bedrock prompt caching documentation
+ * @public
+ */
+declare function bedrockPromptCachingMiddleware(middlewareOptions?: BedrockConversePromptCachingMiddlewareConfig): AgentMiddleware<undefined, z.ZodObject<{
+  /**
+   * Whether to enable prompt caching.
+   * @default true
+   */
+  enableCaching: z.ZodOptional<z.ZodBoolean>;
+  /**
+   * The time-to-live for the cached prompt.
+   * @default "5m"
+   */
+  ttl: z.ZodOptional<z.ZodEnum<["5m", "1h"]>>;
+  /**
+   * The minimum number of messages required before caching is applied.
+   * @default 1
+   */
+  minMessagesToCache: z.ZodOptional<z.ZodNumber>;
+  /**
+   * The behavior to take when an unsupported model is used.
+   * - "ignore" will ignore the unsupported model and continue without caching.
+   * - "warn" will warn the user and continue without caching.
+   * - "raise" will raise an error and stop the agent.
+   * @default "warn"
+   */
+  unsupportedModelBehavior: z.ZodOptional<z.ZodEnum<["ignore", "warn", "raise"]>>;
+}, "strip", z.ZodTypeAny, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}>, {
+  enableCaching?: boolean | undefined;
+  ttl?: "1h" | "5m" | undefined;
+  minMessagesToCache?: number | undefined;
+  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
+}, readonly (_$_langchain_core_tools0.ServerTool | _$_langchain_core_tools0.ClientTool)[], readonly []>;
+//#endregion
+export { BedrockConversePromptCachingMiddlewareConfig, bedrockPromptCachingMiddleware };
+//# sourceMappingURL=promptCaching.d.ts.map

package/dist/agents/middleware/provider/aws/promptCaching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptCaching.d.ts","names":[],"sources":["../../../../../src/agents/middleware/provider/aws/promptCaching.ts"],"mappings":";;;;;;cAWM,aAAA,EAAa,CAAA,CAAA,SAAA;;;;AAVgD;;;;;;;;;;;;EAUhD;;;;;;;;;;;;;;;;;;;KAyBP,4CAAA,GAA+C,OAAA,CACzD,oBAAA,QAA4B,aAAA;;;;;;;;;;;;;;;;;;AAD9B;;;;;;;;;;;;;AAqIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,8BAAA,CACd,iBAAA,GAAoB,4CAAA,8BAA4C,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAAA,wBAAA,CAAA,UAAA"}