feat: introduces context caching configuration for apps, ported from Python ADK

google-genai-bot · copybara-github · commit 12defeedbaf6 · 2026-02-05T11:15:08.000-08:00
This change introduces ContextCacheConfig, a configuration class for enabling and controlling context caching across all agents within an ADK application. The App class is updated to include an optional ContextCacheConfig, allowing applications to specify caching parameters such as cache intervals, TTL, and minimum token thresholds for caching.

PiperOrigin-RevId: 866030713
diff --git a/core/src/main/java/com/google/adk/agents/ContextCacheConfig.java b/core/src/main/java/com/google/adk/agents/ContextCacheConfig.java
@@ -0,0 +1,59 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.adk.agents;
+
+import java.time.Duration;
+
+/**
+ * Configuration for context caching across all agents in an app.
+ *
+ * <p>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.
+ *
+ * <p>Context caching can significantly reduce costs and improve response times by reusing
+ * previously processed context across multiple requests.
+ *
+ * @param maxInvocations Maximum number of invocations to reuse the same cache before refreshing it.
+ *     Defaults to 10.
+ * @param ttl Time-to-live for cache. Defaults to 1800 seconds (30 minutes).
+ * @param minTokens Minimum estimated request tokens required to enable caching. This compares
+ *     against the estimated total tokens of the request (system instruction + tools + contents).
+ *     Context cache storage may have cost. Set higher to avoid caching small requests where
+ *     overhead may exceed benefits. Defaults to 0.
+ */
+public record ContextCacheConfig(int maxInvocations, Duration ttl, int minTokens) {
+
+  public ContextCacheConfig() {
+    this(10, Duration.ofSeconds(1800), 0);
+  }
+
+  /** Returns TTL as string format for cache creation. */
+  public String getTtlString() {
+    return ttl.getSeconds() + "s";
+  }
+
+  @Override
+  public String toString() {
+    return "ContextCacheConfig(maxInvocations="
+        + maxInvocations
+        + ", ttl="
+        + ttl.getSeconds()
+        + "s, minTokens="
+        + minTokens
+        + ")";
+  }
+}
diff --git a/core/src/main/java/com/google/adk/apps/App.java b/core/src/main/java/com/google/adk/apps/App.java
@@ -17,6 +17,7 @@
 package com.google.adk.apps;
 
 import com.google.adk.agents.BaseAgent;
+import com.google.adk.agents.ContextCacheConfig;
 import com.google.adk.plugins.Plugin;
 import com.google.adk.summarizer.EventsCompactionConfig;
 import com.google.common.collect.ImmutableList;
@@ -41,18 +42,21 @@ public class App {
   private final ImmutableList<? extends Plugin> plugins;
   @Nullable private final EventsCompactionConfig eventsCompactionConfig;
   @Nullable private final ResumabilityConfig resumabilityConfig;
+  @Nullable private final ContextCacheConfig contextCacheConfig;
 
   private App(
       String name,
       BaseAgent rootAgent,
       List<? extends Plugin> plugins,
       @Nullable EventsCompactionConfig eventsCompactionConfig,
-      @Nullable ResumabilityConfig resumabilityConfig) {
+      @Nullable ResumabilityConfig resumabilityConfig,
+      @Nullable ContextCacheConfig contextCacheConfig) {
     this.name = name;
     this.rootAgent = rootAgent;
     this.plugins = ImmutableList.copyOf(plugins);
     this.eventsCompactionConfig = eventsCompactionConfig;
     this.resumabilityConfig = resumabilityConfig;
+    this.contextCacheConfig = contextCacheConfig;
   }
 
   public String name() {
@@ -77,13 +81,19 @@ public ResumabilityConfig resumabilityConfig() {
     return resumabilityConfig;
   }
 
+  @Nullable
+  public ContextCacheConfig contextCacheConfig() {
+    return contextCacheConfig;
+  }
+
   /** Builder for {@link App}. */
   public static class Builder {
     private String name;
     private BaseAgent rootAgent;
     private List<? extends Plugin> plugins = ImmutableList.of();
     @Nullable private EventsCompactionConfig eventsCompactionConfig;
     @Nullable private ResumabilityConfig resumabilityConfig;
+    @Nullable private ContextCacheConfig contextCacheConfig;
 
     @CanIgnoreReturnValue
     public Builder name(String name) {
@@ -115,6 +125,12 @@ public Builder resumabilityConfig(ResumabilityConfig resumabilityConfig) {
       return this;
     }
 
+    @CanIgnoreReturnValue
+    public Builder contextCacheConfig(ContextCacheConfig contextCacheConfig) {
+      this.contextCacheConfig = contextCacheConfig;
+      return this;
+    }
+
     public App build() {
       if (name == null) {
         throw new IllegalStateException("App name must be provided.");
@@ -123,7 +139,8 @@ public App build() {
         throw new IllegalStateException("Root agent must be provided.");
       }
       validateAppName(name);
-      return new App(name, rootAgent, plugins, eventsCompactionConfig, resumabilityConfig);
+      return new App(
+          name, rootAgent, plugins, eventsCompactionConfig, resumabilityConfig, contextCacheConfig);
     }
   }
 
