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

Typescript bindings for langchain

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