From 0cf03f6229179a3598b5a64a9db1d31edd774e3d Mon Sep 17 00:00:00 2001 From: Google Team Member Date: Tue, 10 Nov 2026 05:55:33 -0800 Subject: [PATCH] feat(models)!: bump google-genai to 2.3.0 and keep the Gemini API on v1beta BREAKING CHANGE: a `Client` you pass to `Gemini` now uses google-genai 2.x's `v1` default for the Gemini Developer API, which lacks context caching, the Live API, speech output and `-latest` model aliases. Build the client with `HttpOptions.builder().apiVersion("v1beta")` or set `GOOGLE_GENAI_API_VERSION=beta` to keep them. See https://ai.google.dev/gemini-api/docs/api-versions. PiperOrigin-RevId: 1018148525 --- core/pom.xml | 27 +++ .../java/com/google/adk/models/ApigeeLlm.java | 7 +- .../java/com/google/adk/models/Gemini.java | 47 +++- .../adk/models/GeminiApiVersionTest.java | 210 ++++++++++++++++++ pom.xml | 2 +- tokt/README.md | 2 +- .../adk/tokt/KtRunnerToJavaShowcaseTest.java | 2 +- 7 files changed, 285 insertions(+), 12 deletions(-) create mode 100644 core/src/test/java/com/google/adk/models/GeminiApiVersionTest.java diff --git a/core/pom.xml b/core/pom.xml index 672f3e9342..5f421183a7 100644 --- a/core/pom.xml +++ b/core/pom.xml @@ -337,6 +337,33 @@ + + gemini-api-version + + test + + + GeminiApiVersionTest + + + api-key + false + + + + + gemini-api-version-from-environment + + test + + + GeminiApiVersionTest#apiKeyClient_apiVersionFromEnvironment_isKept + + v1alpha + false + + + diff --git a/core/src/main/java/com/google/adk/models/ApigeeLlm.java b/core/src/main/java/com/google/adk/models/ApigeeLlm.java index 9f357662d9..f79199861f 100644 --- a/core/src/main/java/com/google/adk/models/ApigeeLlm.java +++ b/core/src/main/java/com/google/adk/models/ApigeeLlm.java @@ -117,11 +117,11 @@ private ApigeeLlm( this.geminiDelegate = null; this.chatCompletionsClient = new ChatCompletionsHttpClient(this.httpOptions); } else { - Client.Builder apiClientBuilder = Client.builder().httpOptions(this.httpOptions); + Client.Builder apiClientBuilder = Client.builder(); if (isVertexAiModel(modelName)) { apiClientBuilder.vertexAI(true); } - this.apiClient = apiClientBuilder.build(); + this.apiClient = Gemini.buildOnGeminiApiVersion(apiClientBuilder, this.httpOptions); this.geminiDelegate = new Gemini(modelName, apiClient, /* clientSendsTrackingHeaders= */ true); this.chatCompletionsClient = null; @@ -245,7 +245,8 @@ protected Builder() {} * behavior depends on the {@code GOOGLE_GENAI_USE_VERTEXAI} environment variable. If that * is not set to {@code TRUE} or {@code 1}, it defaults to {@code gemini}. *
  • {@code version} (optional): The API version (e.g., {@code v1}, {@code v1beta}). - * If omitted, the default version for the provider is used. + * If omitted, {@code GOOGLE_GENAI_API_VERSION} is used when set; otherwise {@code gemini} + * defaults to {@code v1beta} and {@code vertex_ai} to {@code v1beta1}. *
  • {@code model_id} (required): The model identifier (e.g., {@code * gemini-2.5-flash}). * diff --git a/core/src/main/java/com/google/adk/models/Gemini.java b/core/src/main/java/com/google/adk/models/Gemini.java index c7fad3537a..65e2724b3b 100644 --- a/core/src/main/java/com/google/adk/models/Gemini.java +++ b/core/src/main/java/com/google/adk/models/Gemini.java @@ -16,6 +16,8 @@ package com.google.adk.models; +import static com.google.common.base.Strings.isNullOrEmpty; + import com.google.adk.internal.http.HttpClientFactory; import com.google.common.annotations.VisibleForTesting; import com.google.common.collect.ImmutableList; @@ -64,6 +66,11 @@ public class Gemini extends BaseLlm { private static final Logger logger = LoggerFactory.getLogger(Gemini.class); + /** The Gemini API version that ADK-built clients use; the genai SDK's default before 2.0. */ + private static final String GEMINI_API_VERSION = "v1beta"; + + private static final String API_VERSION_ENV_VARIABLE_NAME = "GOOGLE_GENAI_API_VERSION"; + private static OkHttpClient prepareHttpClient(@Nullable ExecutorService executorService) { OkHttpClient client = executorService == null @@ -77,17 +84,40 @@ private static OkHttpClient prepareHttpClient(@Nullable ExecutorService executor .build(); } - // Every client ADK builds starts here, so each sends ADK's tracking tag. private static Client.Builder adkClientBuilder(@Nullable ExecutorService executorService) { return Client.builder() - .httpOptions(HttpOptions.builder().headers(TrackingHeaders.GENAI_SDK_HEADERS).build()) .clientOptions( ClientOptions.builder().customHttpClient(prepareHttpClient(executorService)).build()); } + // Every client ADK builds is built here, so each sends ADK's tracking tag. + private static Client buildAdkClient(Client.Builder builder) { + return buildOnGeminiApiVersion( + builder, HttpOptions.builder().headers(TrackingHeaders.GENAI_SDK_HEADERS).build()); + } + + /** + * Builds a client with {@code httpOptions}, on API version {@code v1beta} if it targets the + * Gemini API and neither {@code httpOptions} nor {@code GOOGLE_GENAI_API_VERSION} sets a version. + * The genai SDK defaults the Gemini API to {@code v1}, which lacks context caching, the Live API, + * speech output and the {@code -latest} model aliases. + */ + static Client buildOnGeminiApiVersion(Client.Builder builder, HttpOptions httpOptions) { + Client client = builder.httpOptions(httpOptions).build(); + if (client.vertexAI() + || httpOptions.apiVersion().isPresent() + || !isNullOrEmpty(System.getenv(API_VERSION_ENV_VARIABLE_NAME))) { + return client; + } + // The environment can pick the backend, so only the built client tells which one it targets. + return builder + .httpOptions(httpOptions.toBuilder().apiVersion(GEMINI_API_VERSION).build()) + .build(); + } + private static Client buildApiKeyClient( String apiKey, @Nullable ExecutorService executorService) { - return adkClientBuilder(executorService).apiKey(apiKey).build(); + return buildAdkClient(adkClientBuilder(executorService).apiKey(apiKey)); } private static Client buildVertexClient( @@ -96,11 +126,11 @@ private static Client buildVertexClient( vertexCredentials.project().ifPresent(apiClientBuilder::project); vertexCredentials.location().ifPresent(apiClientBuilder::location); vertexCredentials.credentials().ifPresent(apiClientBuilder::credentials); - return apiClientBuilder.build(); + return buildAdkClient(apiClientBuilder); } private static Client buildDefaultClient(@Nullable ExecutorService executorService) { - return adkClientBuilder(executorService).build(); + return buildAdkClient(adkClientBuilder(executorService)); } private final Client apiClient; @@ -113,6 +143,10 @@ private static Client buildDefaultClient(@Nullable ExecutorService executorServi * client's own headers already carry an ADK tag, requests send two because the SDK does not * expose a client's headers. * + *

    If {@code apiClient} targets the Gemini API with no API version set, google-genai 2.x uses + * {@code v1}, which lacks context caching, the Live API, speech output and the {@code -latest} + * model aliases; build it with {@code HttpOptions.builder().apiVersion("v1beta")} to keep them. + * * @param modelName The name of the Gemini model to use (e.g., "gemini-2.0-flash"). * @param apiClient The genai {@link com.google.genai.Client} instance for making API calls. */ @@ -190,7 +224,8 @@ public Builder modelName(String modelName) { * Sets the explicit {@link com.google.genai.Client} instance for making API calls. If this is * set, apiKey and vertexCredentials will be ignored. * - * @param apiClient The client instance. + * @param apiClient The client instance, used as is; see {@link Gemini#Gemini(String, Client)} + * for its API version. * @return This builder. */ @CanIgnoreReturnValue diff --git a/core/src/test/java/com/google/adk/models/GeminiApiVersionTest.java b/core/src/test/java/com/google/adk/models/GeminiApiVersionTest.java new file mode 100644 index 0000000000..e38d4ee455 --- /dev/null +++ b/core/src/test/java/com/google/adk/models/GeminiApiVersionTest.java @@ -0,0 +1,210 @@ +/* + * 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.models; + +import static com.google.common.truth.Truth.assertThat; +import static java.nio.charset.StandardCharsets.UTF_8; +import static org.junit.Assume.assumeFalse; +import static org.junit.Assume.assumeNotNull; +import static org.junit.Assume.assumeTrue; + +import com.google.common.collect.ImmutableList; +import com.google.common.net.InetAddresses; +import com.google.genai.Client; +import com.google.genai.types.Content; +import com.google.genai.types.HttpOptions; +import com.google.genai.types.Part; +import com.sun.net.httpserver.HttpServer; +import java.io.OutputStream; +import java.net.InetAddress; +import java.net.InetSocketAddress; +import java.util.Optional; +import java.util.concurrent.atomic.AtomicReference; +import java.util.function.Function; +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.JUnit4; + +/** Tests the API version on the path of requests from the genai clients ADK builds. */ +@RunWith(JUnit4.class) +public final class GeminiApiVersionTest { + + @Test + public void apiKeyClient_usesGeminiApiVersion() throws Exception { + assumeGeminiApiWithoutVersion(); + + assertThat(pathRequestedBy(serverUrl -> new Gemini("gemini-test", "test-api-key"))) + .isEqualTo("/v1beta/models/gemini-test:generateContent"); + } + + @Test + public void builderApiKeyClient_usesGeminiApiVersion() throws Exception { + assumeGeminiApiWithoutVersion(); + + assertThat( + pathRequestedBy(serverUrl -> + Gemini.builder().modelName("gemini-test").apiKey("test-api-key").build())) + .isEqualTo("/v1beta/models/gemini-test:generateContent"); + } + + @Test + public void defaultClient_usesGeminiApiVersion() throws Exception { + assumeNotNull(System.getenv("GOOGLE_API_KEY")); + assumeGeminiApiWithoutVersion(); + + assertThat(pathRequestedBy(serverUrl -> Gemini.builder().modelName("gemini-test").build())) + .isEqualTo("/v1beta/models/gemini-test:generateContent"); + } + + @Test + public void apiKeyClient_apiVersionFromEnvironment_isKept() throws Exception { + String apiVersion = System.getenv("GOOGLE_GENAI_API_VERSION"); + // The SDK maps "beta" to v1beta, so only a literal version appears in the path. + assumeTrue(apiVersion != null && apiVersion.startsWith("v")); + assumeGeminiApi(); + + assertThat(pathRequestedBy(serverUrl -> new Gemini("gemini-test", "test-api-key"))) + .isEqualTo("/" + apiVersion + "/models/gemini-test:generateContent"); + } + + @Test + public void apigeeGeminiModelWithoutVersion_usesGeminiApiVersion() throws Exception { + assumeNotNull(System.getenv("GOOGLE_API_KEY")); + assumeGeminiApiWithoutVersion(); + + assertThat( + pathRequestedBy(serverUrl -> + ApigeeLlm.builder() + .modelName("apigee/gemini/gemini-test") + .proxyUrl(serverUrl) + .build())) + .isEqualTo("/v1beta/models/gemini-test:generateContent"); + } + + @Test + public void apigeeGeminiModelWithVersion_keepsItsVersion() throws Exception { + assumeNotNull(System.getenv("GOOGLE_API_KEY")); + assumeGeminiApi(); + + assertThat( + pathRequestedBy(serverUrl -> + ApigeeLlm.builder() + .modelName("apigee/gemini/v1/gemini-test") + .proxyUrl(serverUrl) + .build())) + .isEqualTo("/v1/models/gemini-test:generateContent"); + } + + @Test + public void buildOnGeminiApiVersion_explicitVersion_isKept() throws Exception { + assumeGeminiApi(); + + assertThat( + pathRequestedBy(serverUrl -> + new Gemini( + "gemini-test", + Gemini.buildOnGeminiApiVersion( + Client.builder().apiKey("test-api-key"), + HttpOptions.builder().apiVersion("v1alpha").build())))) + .isEqualTo("/v1alpha/models/gemini-test:generateContent"); + } + + @Test + public void buildOnGeminiApiVersion_vertexClient_keepsSdkDefault() throws Exception { + assumeApiVersionUnset(); + + assertThat( + pathRequestedBy(serverUrl -> + new Gemini( + "gemini-test", + Gemini.buildOnGeminiApiVersion( + Client.builder().apiKey("test-api-key").vertexAI(true), + HttpOptions.builder().build())))) + .isEqualTo("/v1beta1/publishers/google/models/gemini-test:generateContent"); + } + + private static void assumeApiVersionUnset() { + String apiVersion = System.getenv("GOOGLE_GENAI_API_VERSION"); + assumeTrue(apiVersion == null || apiVersion.isEmpty()); + } + + /** Skips unless the environment leaves ADK-built clients on the Gemini API. */ + private static void assumeGeminiApi() { + assumeFalse("true".equalsIgnoreCase(System.getenv("GOOGLE_GENAI_USE_VERTEXAI"))); + assumeFalse("true".equalsIgnoreCase(System.getenv("GOOGLE_GENAI_USE_ENTERPRISE"))); + } + + private static void assumeGeminiApiWithoutVersion() { + assumeGeminiApi(); + assumeApiVersionUnset(); + } + + /** + * Sends one request through the model {@code model} builds and returns the path a local server + * received. {@code model} gets the server URL; models that build their own client reach the + * server through {@link Client#setDefaultBaseUrls}. + */ + private static String pathRequestedBy(Function model) + throws Exception { + AtomicReference path = new AtomicReference<>(); + HttpServer server = + HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), 0), 0); + server.createContext( + "/", + exchange -> { + path.set(exchange.getRequestURI().getPath()); + byte[] body = GENERATE_CONTENT_JSON.getBytes(UTF_8); + exchange.getResponseHeaders().set("Content-Type", "application/json"); + exchange.sendResponseHeaders(200, body.length); + try (OutputStream out = exchange.getResponseBody()) { + out.write(body); + } + }); + server.start(); + String serverUrl = + "http://" + + InetAddresses.toUriString(server.getAddress().getAddress()) + + ":" + + server.getAddress().getPort(); + Client.setDefaultBaseUrls(Optional.of(serverUrl), Optional.of(serverUrl)); + try { + assertThat( + model + .apply(serverUrl) + .generateContent(request(), /* stream= */ false) + .toList() + .blockingGet()) + .isNotEmpty(); + return path.get(); + } finally { + Client.setDefaultBaseUrls(Optional.empty(), Optional.empty()); + server.stop(0); + } + } + + private static LlmRequest request() { + return LlmRequest.builder() + .contents( + ImmutableList.of( + Content.builder().role("user").parts(Part.fromText("What is the answer?")).build())) + .build(); + } + + private static final String GENERATE_CONTENT_JSON = + "{\"candidates\":[{\"content\":{\"role\":\"model\",\"parts\":[{\"text\":\"hi\"}]}," + + "\"finishReason\":\"STOP\"}]}"; +} diff --git a/pom.xml b/pom.xml index 78672a8f2e..d6cfd0cea5 100644 --- a/pom.xml +++ b/pom.xml @@ -56,7 +56,7 @@ 1.51.0 2.0.0 2.47.0 - 1.77.0 + 2.3.0 4.33.5 5.11.4 5.23.0 diff --git a/tokt/README.md b/tokt/README.md index 78defdc8c0..1b57dd5d1e 100644 --- a/tokt/README.md +++ b/tokt/README.md @@ -22,7 +22,7 @@ import com.google.adk.tokt.JavaAdkToKt; import com.google.adk.tokt.KotlinAdkToJava; // Your existing ADK Java components: -BaseLlm model = new Gemini("gemini-flash-latest", client); +BaseLlm model = new Gemini("gemini-3.8-flash", client); BaseTool weatherTool = FunctionTool.create(WeatherTools.class, "getWeather"); BaseToolset mathToolset = new MathToolset(); BasePlugin loggingPlugin = new LoggingPlugin(); diff --git a/tokt/src/test/java/com/google/adk/tokt/KtRunnerToJavaShowcaseTest.java b/tokt/src/test/java/com/google/adk/tokt/KtRunnerToJavaShowcaseTest.java index 2794fbcd65..c7dfe8fa38 100644 --- a/tokt/src/test/java/com/google/adk/tokt/KtRunnerToJavaShowcaseTest.java +++ b/tokt/src/test/java/com/google/adk/tokt/KtRunnerToJavaShowcaseTest.java @@ -55,7 +55,7 @@ public void kotlinAgentWithAdaptedJavaComponents_drivenThroughTheJavaRunnerApi() // Ordinary ADK Java components adapted onto the engine: a model and a FunctionTool. Gemini javaModel = - new Gemini("gemini-flash-latest", Client.builder().apiKey(apiKey).vertexAI(false).build()); + new Gemini("gemini-3.8-flash", Client.builder().apiKey(apiKey).vertexAI(false).build()); LlmAgent agent = LlmAgent.builder() .name("assistant")