Feat: Honor GOOGLE_GENAI_USE_ENTERPRISE in getExpressModeApiKey() (adk-python parity)

core/src/models/google_llm.ts

@@ -13,7 +13,7 @@ import {
   LiveServerMessage,
 } from '@google/genai';
 
-import {getBooleanEnvVar, isBrowser} from '../utils/env_aware_utils.js';
+import {isBrowser, isEnterpriseModeEnabled} from '../utils/env_aware_utils.js';
 import {logger} from '../utils/logger.js';
 import {GoogleLLMVariant} from '../utils/variant_utils.js';
 
@@ -373,7 +373,7 @@ export function geminiInitParams({
 
   params.vertexai = !!vertexai;
   if (!params.vertexai && !isBrowser()) {
-    params.vertexai = getBooleanEnvVar('GOOGLE_GENAI_USE_VERTEXAI');
+    params.vertexai = isEnterpriseModeEnabled();
   }
 
   if (params.vertexai) {

core/src/utils/env_aware_utils.ts

@@ -5,6 +5,10 @@
  */
 
 import {randomUUID as nodeRandomUUID} from 'node:crypto';
+import {logger} from './logger.js';
+
+const ENTERPRISE_MODE_ENV_VAR = 'GOOGLE_GENAI_USE_ENTERPRISE';
+const DEPRECATED_ENTERPRISE_MODE_ENV_VAR = 'GOOGLE_GENAI_USE_VERTEXAI';
 
 /**
  * Returns true if the environment is a browser.
@@ -131,3 +135,55 @@ export function getBooleanEnvVar(envVar: string): boolean {
 
   return ['true', '1'].includes(envVarValue);
 }
+
+let warnedDeprecatedEnterpriseModeEnvVar = false;
+
+function warnDeprecatedEnterpriseModeEnvVar(message: string): void {
+  if (warnedDeprecatedEnterpriseModeEnvVar) {
+    return;
+  }
+  warnedDeprecatedEnterpriseModeEnvVar = true;
+  logger.warn(message);
+}
+
+/**
+ * Returns whether Google GenAI enterprise mode is enabled.
+ *
+ * `GOOGLE_GENAI_USE_ENTERPRISE` takes precedence whenever it is set, even when
+ * it is set to a falsy value. `GOOGLE_GENAI_USE_VERTEXAI` is only consulted
+ * when `GOOGLE_GENAI_USE_ENTERPRISE` is absent.
+ *
+ * Setting the deprecated `GOOGLE_GENAI_USE_VERTEXAI` logs a deprecation
+ * warning, whether it is used or overridden. When both variables are set the
+ * warning also states that `GOOGLE_GENAI_USE_VERTEXAI` is ignored, so a stale
+ * value silently overridden by the new variable is still surfaced. This is
+ * read per request, so the warning is logged only once.
+ *
+ * @return True if enterprise mode is enabled, false otherwise.
+ */
+export function isEnterpriseModeEnabled(): boolean {
+  const deprecatedIsSet =
+    process.env?.[DEPRECATED_ENTERPRISE_MODE_ENV_VAR] !== undefined;
+
+  if (process.env?.[ENTERPRISE_MODE_ENV_VAR] !== undefined) {
+    if (deprecatedIsSet) {
+      warnDeprecatedEnterpriseModeEnvVar(
+        `${DEPRECATED_ENTERPRISE_MODE_ENV_VAR} is set but ignored because ` +
+          `${ENTERPRISE_MODE_ENV_VAR} takes precedence. ` +
+          `${DEPRECATED_ENTERPRISE_MODE_ENV_VAR} is deprecated, please use ` +
+          `${ENTERPRISE_MODE_ENV_VAR} instead.`,
+      );
+    }
+    return getBooleanEnvVar(ENTERPRISE_MODE_ENV_VAR);
+  }
+
+  if (deprecatedIsSet) {
+    warnDeprecatedEnterpriseModeEnvVar(
+      `${DEPRECATED_ENTERPRISE_MODE_ENV_VAR} is deprecated, please use ` +
+        `${ENTERPRISE_MODE_ENV_VAR} instead`,
+    );
+    return getBooleanEnvVar(DEPRECATED_ENTERPRISE_MODE_ENV_VAR);
+  }
+
+  return false;
+}

core/src/utils/variant_utils.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {getBooleanEnvVar} from './env_aware_utils.js';
+import {isEnterpriseModeEnabled} from './env_aware_utils.js';
 
 /**
  * The Google LLM variant to use.
@@ -27,7 +27,7 @@ export enum GoogleLLMVariant {
  * Gets the Google LLM variant to use.
  */
 export function getGoogleLlmVariant() {
-  return getBooleanEnvVar('GOOGLE_GENAI_USE_VERTEXAI')
+  return isEnterpriseModeEnabled()
     ? GoogleLLMVariant.VERTEX_AI
     : GoogleLLMVariant.GEMINI_API;
 }

core/src/utils/vertex_ai_utils.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {getBooleanEnvVar} from './env_aware_utils.js';
+import {isEnterpriseModeEnabled} from './env_aware_utils.js';
 
 export const EXPRESS_MODE_UNSUPPORTED_MESSAGE =
   'Vertex AI Express Mode (expressModeApiKey / GOOGLE_API_KEY) is not ' +
@@ -15,6 +15,10 @@ export const EXPRESS_MODE_UNSUPPORTED_MESSAGE =
 /**
  * Validates and returns the API key for Express Mode.
  *
+ * The key is only returned when enterprise mode is enabled via
+ * `GOOGLE_GENAI_USE_ENTERPRISE` (or the deprecated
+ * `GOOGLE_GENAI_USE_VERTEXAI`).
+ *
  * @param project The project id.
  * @param location The location.
  * @param expressModeApiKey The API key for Express Mode.
@@ -32,7 +36,7 @@ export function getExpressModeApiKey(
     );
   }
 
-  if (getBooleanEnvVar('GOOGLE_GENAI_USE_VERTEXAI')) {
+  if (isEnterpriseModeEnabled()) {
     return expressModeApiKey || process.env.GOOGLE_API_KEY;
   }
 

core/test/models/apigee_llm_test.ts

@@ -25,6 +25,7 @@ describe('ApigeeLlm', () => {
     delete process.env['APIGEE_PROXY_URL'];
     delete process.env['GOOGLE_GENAI_API_KEY'];
     delete process.env['GOOGLE_GENAI_USE_VERTEXAI'];
+    delete process.env['GOOGLE_GENAI_USE_ENTERPRISE'];
     delete process.env['GOOGLE_CLOUD_PROJECT'];
     delete process.env['GOOGLE_CLOUD_LOCATION'];
   });

core/test/models/google_llm_test.ts

@@ -64,6 +64,7 @@ describe('GoogleLlm', () => {
     delete process.env['GOOGLE_GENAI_API_KEY'];
     delete process.env['GEMINI_API_KEY'];
     delete process.env['GOOGLE_GENAI_USE_VERTEXAI'];
+    delete process.env['GOOGLE_GENAI_USE_ENTERPRISE'];
     delete process.env['GOOGLE_CLOUD_AGENT_ENGINE_ID'];
   };
 
@@ -335,6 +336,28 @@ describe('GoogleLlm', () => {
       expect(params.vertexai).toBe(true);
     });
 
+    it('should detect Vertex AI from GOOGLE_GENAI_USE_ENTERPRISE', () => {
+      process.env['GOOGLE_GENAI_USE_ENTERPRISE'] = 'true';
+      process.env['GOOGLE_CLOUD_PROJECT'] = 'env-project';
+      process.env['GOOGLE_CLOUD_LOCATION'] = 'env-location';
+      const input = {
+        model: 'gemini-1.5-flash',
+      };
+      const params = geminiInitParams(input);
+      expect(params.vertexai).toBe(true);
+    });
+
+    it('should not use Vertex AI when GOOGLE_GENAI_USE_ENTERPRISE disables it', () => {
+      process.env['GOOGLE_GENAI_USE_ENTERPRISE'] = 'false';
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'true';
+      const input = {
+        model: 'gemini-1.5-flash',
+        apiKey: 'test-key',
+      };
+      const params = geminiInitParams(input);
+      expect(params.vertexai).toBe(false);
+    });
+
     it('should throw error if project is missing for Vertex AI', () => {
       const input = {
         model: 'gemini-1.5-flash',

core/test/utils/env_aware_utils_test.ts

@@ -4,9 +4,18 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {afterEach, describe, expect, it} from 'vitest';
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from 'vitest';
 import {randomUUID as shimRandomUUID} from '../../src/utils/crypto_shim.js';
 import {getBooleanEnvVar, randomUUID} from '../../src/utils/env_aware_utils.js';
+import type {Logger} from '../../src/utils/logger.js';
 
 describe('env_aware_utils', () => {
   describe('getBooleanEnvVar', () => {
@@ -135,4 +144,89 @@ describe('env_aware_utils', () => {
       );
     });
   });
+
+  describe('isEnterpriseModeEnabled', () => {
+    const originalEnv = process.env;
+    let isEnterpriseModeEnabled: () => boolean;
+    let warnSpy: MockInstance<Logger['warn']>;
+
+    beforeEach(async () => {
+      process.env = {...originalEnv};
+      delete process.env['GOOGLE_GENAI_USE_ENTERPRISE'];
+      delete process.env['GOOGLE_GENAI_USE_VERTEXAI'];
+      // The deprecation warning is emitted once per module instance, so each
+      // test needs its own copy of the module and of the logger it warns to.
+      vi.resetModules();
+      const {logger} = await import('../../src/utils/logger.js');
+      warnSpy = vi.spyOn(logger, 'warn').mockImplementation(() => {});
+      ({isEnterpriseModeEnabled} =
+        await import('../../src/utils/env_aware_utils.js'));
+    });
+
+    afterEach(() => {
+      process.env = originalEnv;
+      vi.restoreAllMocks();
+    });
+
+    it('should return false and not warn when neither variable is set', () => {
+      expect(isEnterpriseModeEnabled()).toBe(false);
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should return true when GOOGLE_GENAI_USE_ENTERPRISE is enabled', () => {
+      process.env['GOOGLE_GENAI_USE_ENTERPRISE'] = 'true';
+      expect(isEnterpriseModeEnabled()).toBe(true);
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should prefer an enabled GOOGLE_GENAI_USE_ENTERPRISE over GOOGLE_GENAI_USE_VERTEXAI', () => {
+      process.env['GOOGLE_GENAI_USE_ENTERPRISE'] = 'true';
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'false';
+      expect(isEnterpriseModeEnabled()).toBe(true);
+    });
+
+    it('should not fall back to GOOGLE_GENAI_USE_VERTEXAI when GOOGLE_GENAI_USE_ENTERPRISE is set but disabled', () => {
+      process.env['GOOGLE_GENAI_USE_ENTERPRISE'] = '';
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'true';
+      expect(isEnterpriseModeEnabled()).toBe(false);
+    });
+
+    it('should warn that GOOGLE_GENAI_USE_VERTEXAI is ignored when both variables are set', () => {
+      process.env['GOOGLE_GENAI_USE_ENTERPRISE'] = 'true';
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'true';
+      expect(isEnterpriseModeEnabled()).toBe(true);
+      expect(warnSpy).toHaveBeenCalledOnce();
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'GOOGLE_GENAI_USE_VERTEXAI is set but ignored because ' +
+            'GOOGLE_GENAI_USE_ENTERPRISE takes precedence',
+        ),
+      );
+    });
+
+    it('should fall back to an enabled GOOGLE_GENAI_USE_VERTEXAI and warn', () => {
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'true';
+      expect(isEnterpriseModeEnabled()).toBe(true);
+      expect(warnSpy).toHaveBeenCalledOnce();
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'GOOGLE_GENAI_USE_VERTEXAI is deprecated, please use ' +
+            'GOOGLE_GENAI_USE_ENTERPRISE',
+        ),
+      );
+    });
+
+    it('should warn when GOOGLE_GENAI_USE_VERTEXAI is present but disabled', () => {
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'false';
+      expect(isEnterpriseModeEnabled()).toBe(false);
+      expect(warnSpy).toHaveBeenCalledOnce();
+    });
+
+    it('should warn only once even when read repeatedly', () => {
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'true';
+      expect(isEnterpriseModeEnabled()).toBe(true);
+      expect(isEnterpriseModeEnabled()).toBe(true);
+      expect(warnSpy).toHaveBeenCalledOnce();
+    });
+  });
 });

core/test/utils/variant_utils_test.ts

@@ -5,34 +5,53 @@
  */
 
 import {GoogleLLMVariant} from '@google/adk';
-import {afterEach, describe, expect, it} from 'vitest';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {logger} from '../../src/utils/logger.js';
 import {getGoogleLlmVariant} from '../../src/utils/variant_utils.js';
 
 describe('variant_utils', () => {
   describe('getGoogleLlmVariant', () => {
     const originalEnv = process.env;
 
+    beforeEach(() => {
+      process.env = {...originalEnv};
+      delete process.env['GOOGLE_GENAI_USE_ENTERPRISE'];
+      delete process.env['GOOGLE_GENAI_USE_VERTEXAI'];
+      vi.spyOn(logger, 'warn').mockImplementation(() => {});
+    });
+
     afterEach(() => {
       process.env = originalEnv;
+      vi.restoreAllMocks();
     });
 
     it('should return GEMINI_API by default (when env var is not set)', () => {
-      delete process.env['GOOGLE_GENAI_USE_VERTEXAI'];
       expect(getGoogleLlmVariant()).toBe(GoogleLLMVariant.GEMINI_API);
     });
 
     it('should return VERTEX_AI when GOOGLE_GENAI_USE_VERTEXAI is "true"', () => {
-      process.env = {...originalEnv, 'GOOGLE_GENAI_USE_VERTEXAI': 'true'};
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'true';
       expect(getGoogleLlmVariant()).toBe(GoogleLLMVariant.VERTEX_AI);
     });
 
     it('should return VERTEX_AI when GOOGLE_GENAI_USE_VERTEXAI is "1"', () => {
-      process.env = {...originalEnv, 'GOOGLE_GENAI_USE_VERTEXAI': '1'};
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = '1';
       expect(getGoogleLlmVariant()).toBe(GoogleLLMVariant.VERTEX_AI);
     });
 
     it('should return GEMINI_API when GOOGLE_GENAI_USE_VERTEXAI is "false"', () => {
-      process.env = {...originalEnv, 'GOOGLE_GENAI_USE_VERTEXAI': 'false'};
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'false';
+      expect(getGoogleLlmVariant()).toBe(GoogleLLMVariant.GEMINI_API);
+    });
+
+    it('should return VERTEX_AI when GOOGLE_GENAI_USE_ENTERPRISE is "true"', () => {
+      process.env['GOOGLE_GENAI_USE_ENTERPRISE'] = 'true';
+      expect(getGoogleLlmVariant()).toBe(GoogleLLMVariant.VERTEX_AI);
+    });
+
+    it('should return GEMINI_API when GOOGLE_GENAI_USE_ENTERPRISE is "false" and GOOGLE_GENAI_USE_VERTEXAI is "true"', () => {
+      process.env['GOOGLE_GENAI_USE_ENTERPRISE'] = 'false';
+      process.env['GOOGLE_GENAI_USE_VERTEXAI'] = 'true';
       expect(getGoogleLlmVariant()).toBe(GoogleLLMVariant.GEMINI_API);
     });
   });