feat: introduce enterprise flag and GOOGLE_GENAI_USE_ENTERPRISE env var

PiperOrigin-RevId: 903940734

Author: yyyu-google

README.md

@@ -29,7 +29,7 @@ We recommend using our Code Generation instructions [`codegen_instructions.md`](
 
 1. Node.js version 20 or later
 
-### The following are required for Vertex AI users (excluding Vertex AI Studio)
+### The following are required for Gemini Enterprise Agent Platform users (excluding Vertex AI Studio)
 1.  [Select](https://console.cloud.google.com/project) or [create](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project) a Google Cloud project.
 1.  [Enable billing for your project](https://cloud.google.com/billing/docs/how-to/modify-project).
 1.  [Enable the Vertex AI API](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com).
@@ -77,7 +77,7 @@ main();
 
 The Google Gen AI SDK provides support for both the
 [Google AI Studio](https://ai.google.dev/gemini-api/docs) and
-[Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview)
+[Gemini Enterprise Agent Platform](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview)
  implementations of the Gemini API.
 
 ### Gemini Developer API
@@ -104,15 +104,15 @@ import { GoogleGenAI } from '@google/genai';
 const ai = new GoogleGenAI({apiKey: 'GEMINI_API_KEY'});
 ```
 
-### Vertex AI
+### Gemini Enterprise Agent Platform
 
-Sample code for VertexAI initialization:
+Sample code for Gemini Enterprise Agent Platform initialization:
 
 ```typescript
 import { GoogleGenAI } from '@google/genai';
 
 const ai = new GoogleGenAI({
-    vertexai: true,
+    enterprise: true,
     project: 'your_project',
     location: 'your_location',
 });
@@ -122,19 +122,19 @@ const ai = new GoogleGenAI({
 
 For NodeJS environments, you can create a client by configuring the necessary
 environment variables. Configuration setup instructions depends on whether
-you're using the Gemini Developer API or the Gemini API in Vertex AI.
+you're using the Gemini Developer API or the Gemini Enterprise Agent Platform.
 
 **Gemini Developer API:** Set `GOOGLE_API_KEY` as shown below:
 
 ```bash
 export GOOGLE_API_KEY='your-api-key'
 ```
 
-**Gemini API on Vertex AI:** Set `GOOGLE_GENAI_USE_VERTEXAI`,
+**Gemini Enterprise Agent Platform:** Set `GOOGLE_GENAI_USE_ENTERPRISE`,
 `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`, as shown below:
 
 ```bash
-export GOOGLE_GENAI_USE_VERTEXAI=true
+export GOOGLE_GENAI_USE_ENTERPRISE=true
 export GOOGLE_CLOUD_PROJECT='your-project-id'
 export GOOGLE_CLOUD_LOCATION='us-central1'
 ```
@@ -152,11 +152,11 @@ preview features in the APIs. The stable API endpoints can be selected by
 setting the API version to `v1`.
 
 To set the API version use `apiVersion`. For example, to set the API version to
-`v1` for Vertex AI:
+`v1` for Gemini Enterprise Agent Platform:
 
 ```typescript
 const ai = new GoogleGenAI({
-    vertexai: true,
+    enterprise: true,
     project: 'your_project',
     location: 'your_location',
     apiVersion: 'v1'
@@ -600,7 +600,7 @@ for (const output of interaction.outputs!) {
 This SDK (`@google/genai`) is Google Deepmind’s "vanilla" SDK for its generative
 AI offerings, and is where Google Deepmind adds new AI features.
 
-Models hosted either on the [Vertex AI platform](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) or the [Gemini Developer platform](https://ai.google.dev/gemini-api/docs) are accessible through this SDK.
+Models hosted either on the [Gemini Enterprise Agent Platform](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) or the [Gemini Developer platform](https://ai.google.dev/gemini-api/docs) are accessible through this SDK.
 
 Other SDKs may be offering additional AI frameworks on top of this SDK, or may
 be targeting specific project environments (like Firebase).

api-report/genai-node.api.md

@@ -1807,6 +1807,7 @@ export class GoogleGenAI {
 export interface GoogleGenAIOptions {
     apiKey?: string;
     apiVersion?: string;
+    enterprise?: boolean;
     googleAuthOptions?: GoogleAuthOptions;
     httpOptions?: HttpOptions;
     location?: string;

api-report/genai-web.api.md

@@ -1807,6 +1807,7 @@ export class GoogleGenAI {
 export interface GoogleGenAIOptions {
     apiKey?: string;
     apiVersion?: string;
+    enterprise?: boolean;
     googleAuthOptions?: GoogleAuthOptions;
     httpOptions?: HttpOptions;
     location?: string;

api-report/genai.api.md

@@ -1807,6 +1807,7 @@ export class GoogleGenAI {
 export interface GoogleGenAIOptions {
     apiKey?: string;
     apiVersion?: string;
+    enterprise?: boolean;
     googleAuthOptions?: GoogleAuthOptions;
     httpOptions?: HttpOptions;
     location?: string;

src/client.ts

@@ -39,8 +39,23 @@ export interface GoogleGenAIOptions {
    * Optional. Determines whether to use the Vertex AI or the Gemini API.
    *
    * @remarks
+   * When true, the {@link https://cloud.google.com/vertex-ai/docs/reference/rest | Gemini Enterprise Agent Platform API} will used.
+   * When false, the {@link https://ai.google.dev/api | Gemini API} will be used.
+   * When both enterprise and vertexai are set, and they have different values,
+   * an Error will be thrown.
+   *
+   * If unset, default SDK behavior is to use the Gemini API service.
+   */
+  enterprise?: boolean;
+  /**
+   * Optional. Determines whether to use the Vertex AI (now Gemini Enterprise Agent Platform) or the Gemini API.
+   * The `enterprise` flag is recommended instead.
+   *
+   * @remarks
    * When true, the {@link https://cloud.google.com/vertex-ai/docs/reference/rest | Vertex AI API} will used.
    * When false, the {@link https://ai.google.dev/api | Gemini API} will be used.
+   * When both enterprise and vertexai are set, and they have different values,
+   * an Error will be thrown.
    *
    * If unset, default SDK behavior is to use the Gemini API service.
    */
@@ -195,7 +210,16 @@ export class GoogleGenAI {
         `An API Key must be set when running in an unspecified environment.\n + ${crossError().message}`,
       );
     }
-    this.vertexai = options.vertexai ?? false;
+    if (
+      options.enterprise !== undefined &&
+      options.vertexai !== undefined &&
+      options.enterprise !== options.vertexai
+    ) {
+      throw new Error(
+        'enterprise and vertexAI flags have conflicting values, please set enterprise value only.',
+      );
+    }
+    this.vertexai = options.enterprise ?? options.vertexai ?? false;
     this.apiKey = options.apiKey;
     this.apiVersion = options.apiVersion;
     this.httpOptions = options.httpOptions;

src/node/node_client.ts

@@ -32,6 +32,45 @@ import {NodeFiles} from './node_files.js';
 
 const LANGUAGE_LABEL_PREFIX = 'gl-node/';
 
+function resolveCloudFlag(options: GoogleGenAIOptions): boolean {
+  if (options.enterprise !== undefined || options.vertexai !== undefined) {
+    if (
+      options.enterprise !== undefined &&
+      options.vertexai !== undefined &&
+      options.enterprise !== options.vertexai
+    ) {
+      throw new Error(
+        'enterprise and vertexAI flags have conflicting values, please set enterprise value only.',
+      );
+    }
+    return options.enterprise ?? options.vertexai!;
+  }
+
+  const envEnterpriseStr = getEnv('GOOGLE_GENAI_USE_ENTERPRISE');
+  const envVertexaiStr = getEnv('GOOGLE_GENAI_USE_VERTEXAI');
+  const useEnterpriseEnv = stringToBoolean(envEnterpriseStr);
+  const useVertexaiEnv = stringToBoolean(envVertexaiStr);
+
+  if (
+    envEnterpriseStr !== undefined &&
+    envVertexaiStr !== undefined &&
+    useEnterpriseEnv !== useVertexaiEnv
+  ) {
+    console.warn(
+      'Warning: Both GOOGLE_GENAI_USE_ENTERPRISE and GOOGLE_GENAI_USE_VERTEXAI are set with conflicting values. The value of GOOGLE_GENAI_USE_ENTERPRISE will be used.',
+    );
+  }
+
+  if (envEnterpriseStr !== undefined) {
+    return useEnterpriseEnv;
+  }
+  if (envVertexaiStr !== undefined) {
+    return useVertexaiEnv;
+  }
+
+  return false;
+}
+
 /**
  * The Google GenAI SDK.
  *
@@ -148,8 +187,7 @@ export class GoogleGenAI {
       );
     }
 
-    this.vertexai =
-      options.vertexai ?? getBooleanEnv('GOOGLE_GENAI_USE_VERTEXAI') ?? false;
+    this.vertexai = resolveCloudFlag(options);
     const envApiKey = getApiKeyFromEnv();
     const envProject = getEnv('GOOGLE_CLOUD_PROJECT');
     const envLocation = getEnv('GOOGLE_CLOUD_LOCATION');
@@ -163,7 +201,7 @@ export class GoogleGenAI {
     }
 
     // Handle when to use Vertex AI in express mode (api key)
-    if (options.vertexai) {
+    if (this.vertexai) {
       if (options.googleAuthOptions?.credentials) {
         // Explicit credentials take precedence over implicit api_key.
         console.debug(
@@ -204,7 +242,7 @@ export class GoogleGenAI {
 
     const baseUrl = getBaseUrl(
       options.httpOptions,
-      options.vertexai,
+      this.vertexai,
       getEnv('GOOGLE_VERTEX_BASE_URL'),
       getEnv('GOOGLE_GEMINI_BASE_URL'),
     );
@@ -251,10 +289,6 @@ function getEnv(env: string): string | undefined {
   return process?.env?.[env]?.trim() ?? undefined;
 }
 
-function getBooleanEnv(env: string): boolean {
-  return stringToBoolean(getEnv(env));
-}
-
 function stringToBoolean(str?: string): boolean {
   if (str === undefined) {
     return false;

test/unit/node/base_url_test.ts

@@ -11,6 +11,8 @@ describe('setDefaultBaseUrls', () => {
   afterEach(() => {
     delete process.env['GOOGLE_GEMINI_BASE_URL'];
     delete process.env['GOOGLE_VERTEX_BASE_URL'];
+    delete process.env['GOOGLE_GENAI_USE_ENTERPRISE'];
+    delete process.env['GOOGLE_GENAI_USE_VERTEXAI'];
 
     setDefaultBaseUrls({});
   });