feat: context caching

apps/docs/content/docs/framework/context/context-caching.mdx

@@ -0,0 +1,35 @@
+---
+title: Context caching with Gemini
+description: This document explains how to configure and use the context caching feature.
+---
+
+When working with agents to complete tasks, you may want to reuse extended instructions or large sets of data across multiple agent requests to a generative AI model. Resending this data for each agent request is slow, inefficient, and can be expensive. Using context caching features in generative AI models can significantly speed up responses and lower the number of tokens sent to the model for each request.
+
+The ADK Context Caching feature allows you to cache request data with generative AI models that support it, including Gemini 2.0 and higher models. This document explains how to configure and use this feature.
+
+
+## Configure context caching
+
+You configure the context caching feature when creating your agent by passing a `contextCacheConfig` object directly to your agent. For example:
+
+```typescript
+const agent = new LlmAgent({
+  model: "gemini-2.5-flash", // Configure an agent using a model that supports context caching
+  // ... other agent properties
+  contextCacheConfig: {
+      cacheIntervals: 10,
+      ttlSeconds: 1800,
+      minTokens: 1000,
+  },
+});
+```
+
+## Configuration settings
+
+The `contextCacheConfig` object has the following settings that control how caching works for your agent:
+
+* **minTokens** (`number`): The minimum number of tokens required in a request to enable caching. This avoids caching very small requests where the performance benefit is negligible. **Default:** `0`.
+
+* **ttlSeconds** (`number`): The time-to-live (TTL) for the cache in seconds. Determines how long cached content is stored before it is refreshed. **Default:** `1800` (30 minutes).
+
+* **cacheIntervals** (`number`): The maximum number of times the same cached content can be used before it expires. Allows control over how frequently the cache is updated, even if the TTL has not expired. **Default:** `10`.

apps/docs/content/docs/framework/context/meta.json

@@ -5,7 +5,8 @@
 		"callback-context",
 		"tool-context",
 		"invocation-context",
-		"context-patterns"
+		"context-patterns",
+		"context-caching"
 	],
 	"icon": "Brain"
 }

packages/adk/src/agents/agent-builder.ts

@@ -20,6 +20,10 @@ import type {
 	BaseAgent,
 	BeforeAgentCallback,
 } from "./base-agent.js";
+import {
+	ContextCacheConfig,
+	type ContextCacheConfigProps,
+} from "./context-cache-config.js";
 import { LangGraphAgent, type LangGraphNode } from "./lang-graph-agent.js";
 import type {
 	AfterModelCallback,
@@ -155,6 +159,7 @@ interface RunnerConfig {
 	memoryService?: BaseMemoryService;
 	artifactService?: BaseArtifactService;
 	eventsCompactionConfig?: EventsCompactionConfig;
+	contextCacheConfig?: ContextCacheConfig;
 }
 
 /**
@@ -208,6 +213,7 @@ export class AgentBuilder<TOut = string, TMulti extends boolean = false> {
 	private memoryService?: BaseMemoryService;
 	private artifactService?: BaseArtifactService;
 	private eventsCompactionConfig?: EventsCompactionConfig;
+	private cacheConfig?: ContextCacheConfig;
 	private agentType: AgentType = "llm";
 	private existingSession?: Session;
 	private existingAgent?: BaseAgent; // If provided, reuse directly
@@ -648,6 +654,33 @@ export class AgentBuilder<TOut = string, TMulti extends boolean = false> {
 		return this;
 	}
 
+	/**
+	 * Configure context caching for Gemini models
+	 * @param config Cache configuration options (cacheIntervals, ttlSeconds, minTokens)
+	 * @returns This builder instance for chaining
+	 * @example
+	 * ```typescript
+	 * const { runner } = await AgentBuilder
+	 *   .create("assistant")
+	 *   .withModel("gemini-2.5-flash")
+	 *   .withCacheConfig({
+	 *     cacheIntervals: 10,  // Reuse cache for 10 invocations
+	 *     ttlSeconds: 1800,    // Cache expires after 30 minutes
+	 *     minTokens: 1000,     // Only cache if request has 1000+ tokens
+	 *   })
+	 *   .build();
+	 * ```
+	 */
+	withCacheConfig(
+		config: Partial<ContextCacheConfigProps> | ContextCacheConfig,
+	): this {
+		this.cacheConfig =
+			config instanceof ContextCacheConfig
+				? config
+				: new ContextCacheConfig(config);
+		return this;
+	}
+
 	/**
 	 * Configure runtime behavior for runs
 	 */
@@ -724,6 +757,7 @@ export class AgentBuilder<TOut = string, TMulti extends boolean = false> {
 				memoryService: this.memoryService,
 				artifactService: this.artifactService,
 				eventsCompactionConfig: this.eventsCompactionConfig,
+				contextCacheConfig: this.cacheConfig,
 			};
 
 			const baseRunner = new Runner(runnerConfig);

packages/adk/src/agents/base-agent.ts

@@ -2,6 +2,7 @@ import type { Content } from "@google/genai";
 import { Event } from "../events/event";
 import { telemetryService } from "../telemetry";
 import { CallbackContext } from "./callback-context";
+import { ContextCacheConfig } from "./context-cache-config";
 import type { InvocationContext } from "./invocation-context";
 
 /**
@@ -83,6 +84,8 @@ export abstract class BaseAgent {
 	 */
 	afterAgentCallback?: AfterAgentCallback;
 
+	contextCacheConfig?: ContextCacheConfig;
+
 	/**
 	 * Constructor for BaseAgent
 	 */
@@ -92,12 +95,14 @@ export abstract class BaseAgent {
 		subAgents?: BaseAgent[];
 		beforeAgentCallback?: BeforeAgentCallback;
 		afterAgentCallback?: AfterAgentCallback;
+		contextCacheConfig?: ContextCacheConfig;
 	}) {
 		this.name = config.name;
 		this.description = config.description || "";
 		this.subAgents = config.subAgents || [];
 		this.beforeAgentCallback = config.beforeAgentCallback;
 		this.afterAgentCallback = config.afterAgentCallback;
+		this.contextCacheConfig = config.contextCacheConfig;
 
 		// Validate agent name
 		this.validateName(this.name);

packages/adk/src/agents/context-cache-config.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+
+/**
+ * Zod schema defining validation rules for ContextCacheConfig.
+ */
+export const contextCacheConfigSchema = z.object({
+	/**
+	 * Maximum number of invocations to reuse the same cache before refreshing it.
+	 * Must be between 1 and 100.
+	 *
+	 * @default 10
+	 */
+	cacheIntervals: z
+		.number()
+		.int()
+		.min(1, { message: "cacheIntervals must be at least 1." })
+		.max(100, { message: "cacheIntervals must not exceed 100." })
+		.default(10),
+
+	/**
+	 * Time-to-live for cache in seconds. Must be greater than 0.
+	 * Default: 1800 (30 minutes).
+	 *
+	 * @default 1800
+	 */
+	ttlSeconds: z
+		.number()
+		.int()
+		.positive({ message: "ttlSeconds must be greater than 0." })
+		.default(1800),
+
+	/**
+	 * Minimum estimated request tokens required to enable caching.
+	 * Set higher to avoid caching small requests where overhead may exceed benefits.
+	 *
+	 * @default 0
+	 */
+	minTokens: z
+		.number()
+		.int()
+		.min(0, { message: "minTokens must be non-negative." })
+		.default(0),
+});
+
+/**
+ * Inferred TypeScript type for ContextCacheConfig properties.
+ */
+export type ContextCacheConfigProps = z.infer<typeof contextCacheConfigSchema>;
+
+/**
+ * Configuration for context caching across all agents in an app.
+ *
+ * This configuration enables and controls context caching behavior for
+ * all LLM agents in an app. When this config is present on an app, context
+ * caching is enabled for all agents. When absent (null), context caching
+ * is disabled.
+ *
+ * Context caching can significantly reduce costs and improve response times
+ * by reusing previously processed context across multiple requests.
+ */
+export class ContextCacheConfig implements ContextCacheConfigProps {
+	/** Maximum number of invocations to reuse the same cache before refreshing it. */
+	public cacheIntervals: number;
+
+	/** Time-to-live for cache in seconds. */
+	public ttlSeconds: number;
+
+	/** Minimum estimated request tokens required to enable caching. */
+	public minTokens: number;
+
+	/**
+	 * Creates a new validated ContextCacheConfig instance.
+	 *
+	 */
+	constructor(params: Partial<ContextCacheConfigProps> = {}) {
+		const validated = contextCacheConfigSchema.parse(params);
+		this.cacheIntervals = validated.cacheIntervals;
+		this.ttlSeconds = validated.ttlSeconds;
+		this.minTokens = validated.minTokens;
+	}
+
+	/**
+	 * Returns the TTL as a formatted string (e.g., "1800s").
+	 *
+	 */
+	get ttlString(): string {
+		return `${this.ttlSeconds}s`;
+	}
+
+	/**
+	 * Returns a readable string representation of the configuration,
+	 * useful for debugging or logging.
+	 */
+	toString(): string {
+		return `ContextCacheConfig(cache_intervals=${this.cacheIntervals}, ttl=${this.ttlSeconds}s, min_tokens=${this.minTokens})`;
+	}
+
+	/**
+	 * Validates a plain object and returns a new `ContextCacheConfig` instance.
+	 *
+	 */
+	static from(data: unknown): ContextCacheConfig {
+		const validated = contextCacheConfigSchema.parse(data);
+		return new ContextCacheConfig(validated);
+	}
+
+	/**
+	 * Converts the configuration to a plain JavaScript object.
+	 *
+	 */
+	toJSON(): ContextCacheConfigProps {
+		return {
+			cacheIntervals: this.cacheIntervals,
+			ttlSeconds: this.ttlSeconds,
+			minTokens: this.minTokens,
+		};
+	}
+}

packages/adk/src/agents/index.ts

@@ -1,11 +1,12 @@
+export * from "./agent-builder";
 export * from "./base-agent";
+export * from "./callback-context";
+export * from "./context-cache-config";
+export * from "./invocation-context";
+export * from "./lang-graph-agent";
 export * from "./llm-agent";
-export * from "./sequential-agent";
-export * from "./parallel-agent";
 export * from "./loop-agent";
-export * from "./lang-graph-agent";
-export * from "./agent-builder";
-export * from "./run-config";
-export * from "./invocation-context";
+export * from "./parallel-agent";
 export * from "./readonly-context";
-export * from "./callback-context";
+export * from "./run-config";
+export * from "./sequential-agent";

packages/adk/src/agents/invocation-context.ts

@@ -5,6 +5,7 @@ import type { BaseSessionService } from "../sessions/base-session-service";
 import type { Session } from "../sessions/session";
 import type { ActiveStreamingTool } from "./active-streaming-tool";
 import type { BaseAgent } from "./base-agent";
+import { ContextCacheConfig } from "./context-cache-config";
 import type { LiveRequestQueue } from "./live-request-queue";
 import type { RunConfig } from "./run-config";
 import type { TranscriptionEntry } from "./transcription-entry";
@@ -103,6 +104,7 @@ export class InvocationContext {
 	readonly artifactService?: BaseArtifactService;
 	readonly sessionService: BaseSessionService;
 	readonly memoryService?: BaseMemoryService;
+	readonly contextCacheConfig?: ContextCacheConfig;
 
 	/**
 	 * The id of this invocation context. Readonly.
@@ -186,6 +188,7 @@ export class InvocationContext {
 		activeStreamingTools?: Record<string, ActiveStreamingTool>;
 		transcriptionCache?: TranscriptionEntry[];
 		runConfig?: RunConfig;
+		contextCacheConfig?: ContextCacheConfig;
 	}) {
 		this.artifactService = options.artifactService;
 		this.sessionService = options.sessionService;
@@ -200,6 +203,7 @@ export class InvocationContext {
 		this.activeStreamingTools = options.activeStreamingTools;
 		this.transcriptionCache = options.transcriptionCache;
 		this.runConfig = options.runConfig;
+		this.contextCacheConfig = options.contextCacheConfig;
 	}
 
 	/**
@@ -245,6 +249,7 @@ export class InvocationContext {
 			activeStreamingTools: this.activeStreamingTools,
 			transcriptionCache: this.transcriptionCache,
 			runConfig: this.runConfig,
+			contextCacheConfig: this.contextCacheConfig,
 		});
 	}
 }

packages/adk/src/agents/llm-agent.ts

@@ -23,6 +23,7 @@ import {
 	type BeforeAgentCallback,
 } from "./base-agent";
 import type { CallbackContext } from "./callback-context";
+import { ContextCacheConfig } from "./context-cache-config";
 import type { InvocationContext } from "./invocation-context";
 import type { ReadonlyContext } from "./readonly-context";
 
@@ -252,6 +253,11 @@ export interface LlmAgentConfig<T extends BaseLlm = BaseLlm> {
 	 * Callback or list of callbacks to be called after calling a tool
 	 */
 	afterToolCallback?: AfterToolCallback;
+
+	/**
+	 * Context cache configuration for Gemini models
+	 */
+	contextCacheConfig?: ContextCacheConfig;
 }
 
 /**
@@ -382,6 +388,7 @@ export class LlmAgent<T extends BaseLlm = BaseLlm> extends BaseAgent {
 			subAgents: config.subAgents,
 			beforeAgentCallback: config.beforeAgentCallback,
 			afterAgentCallback: config.afterAgentCallback,
+			contextCacheConfig: config.contextCacheConfig,
 		});
 
 		this.model = config.model || "";

packages/adk/src/flows/llm-flows/base-llm-flow.ts

@@ -77,7 +77,9 @@ export abstract class BaseLlmFlow {
 	async *_runOneStepAsync(
 		invocationContext: InvocationContext,
 	): AsyncGenerator<Event> {
-		const llmRequest = new LlmRequest();
+		const llmRequest = new LlmRequest({
+			cacheConfig: invocationContext.contextCacheConfig,
+		});
 
 		// Preprocessing phase
 		for await (const event of this._preprocessAsync(