@google/adk 0.3.0 → 0.4.0

package/dist/esm/models/apigee_llm.js

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isBrowser } from "../utils/env_aware_utils.js";
+import { logger } from "../utils/logger.js";
+import { Gemini, geminiInitParams } from "./google_llm.js";
+const APIGEE_PROXY_URL_ENV_VARIABLE_NAME = "APIGEE_PROXY_URL";
+class ApigeeLlm extends Gemini {
+  constructor({
+    model,
+    proxyUrl,
+    apiKey,
+    vertexai,
+    location,
+    project,
+    headers
+  }) {
+    var _a;
+    if (!validateModel(model)) {
+      throw new Error(
+        `Model ${model} is not a valid Apigee model, expected apigee/[<provider>/][<version>/]<model_id>`
+      );
+    }
+    super({
+      ...apigeeToGeminiInitParams({ model, vertexai, project, location, apiKey }),
+      headers
+    });
+    this.proxyUrl = proxyUrl != null ? proxyUrl : "";
+    if (!isBrowser() && !this.proxyUrl) {
+      this.proxyUrl = (_a = process.env[APIGEE_PROXY_URL_ENV_VARIABLE_NAME]) != null ? _a : "";
+    }
+    if (!this.proxyUrl) {
+      throw new Error(
+        `Proxy URL must be provided via the constructor or ${APIGEE_PROXY_URL_ENV_VARIABLE_NAME} environment variable.`
+      );
+    }
+  }
+  getHttpOptions() {
+    const opts = super.getHttpOptions();
+    opts.baseUrl = this.proxyUrl;
+    return opts;
+  }
+  getLiveHttpOptions() {
+    const opts = super.getLiveHttpOptions();
+    opts.baseUrl = this.proxyUrl;
+    return opts;
+  }
+  identifyApiVersion() {
+    const modelTrimmed = this.model.startsWith("apigee/") ? this.model.substring("apigee/".length) : this.model;
+    const components = modelTrimmed.split("/");
+    if (components.length === 3) {
+      return components[1];
+    }
+    if (components.length === 2) {
+      if (components[0] != "vertex_ai" && components[0] != "gemini" && components[0].startsWith("v")) {
+        return components[0];
+      }
+    }
+    return this.vertexai ? "v1beta1" : "v1alpha";
+  }
+  get liveApiVersion() {
+    if (!this._apigeeLiveApiVersion) {
+      this._apigeeLiveApiVersion = this.identifyApiVersion();
+    }
+    return this._apigeeLiveApiVersion;
+  }
+  async *generateContentAsync(llmRequest, stream = false) {
+    var _a;
+    const modelToUse = (_a = llmRequest.model) != null ? _a : this.model;
+    llmRequest.model = getModelId(modelToUse);
+    yield* super.generateContentAsync(llmRequest, stream);
+  }
+  async connect(llmRequest) {
+    var _a;
+    const modelToUse = (_a = llmRequest.model) != null ? _a : this.model;
+    llmRequest.model = getModelId(modelToUse);
+    return super.connect(llmRequest);
+  }
+}
+/**
+ * A list of model name patterns that are supported by this LLM.
+ *
+ * @returns A list of supported models.
+ */
+ApigeeLlm.supportedModels = [
+  /apigee\/.*/
+];
+function apigeeToGeminiInitParams({
+  model,
+  vertexai,
+  project,
+  location,
+  apiKey
+}) {
+  var _a;
+  const params = geminiInitParams({ model, vertexai, project, location, apiKey });
+  params.vertexai = params.vertexai || ((_a = params.model) == null ? void 0 : _a.startsWith("apigee/vertex_ai/"));
+  if (params.vertexai) {
+    return params;
+  }
+  if (!params.apiKey) {
+    logger.warn(
+      `No API key provided when using a Gemini model, using a fake key "-".`
+    );
+    params.apiKey = "-";
+  }
+  return params;
+}
+function getModelId(model) {
+  if (!validateModel(model)) {
+    throw new Error(
+      `Model ${model} is not a valid Apigee model, expected apigee/[<provider>/][<version>/]<model_id>`
+    );
+  }
+  const components = model.split("/");
+  return components[components.length - 1];
+}
+function validateModel(model) {
+  const validProviders = ["vertex_ai", "gemini"];
+  if (!model.startsWith("apigee/")) {
+    return false;
+  }
+  const modelPart = model.substring("apigee/".length);
+  if (modelPart.length === 0) {
+    return false;
+  }
+  const components = modelPart.split("/", -1);
+  if (components[components.length - 1].length === 0) {
+    return false;
+  }
+  if (components.length == 1) {
+    return true;
+  }
+  if (components.length == 2) {
+    if (validProviders.includes(components[0])) {
+      return true;
+    }
+    return components[0].startsWith("v");
+  }
+  if (components.length == 3) {
+    if (!validProviders.includes(components[0])) {
+      return false;
+    }
+    return components[1].startsWith("v");
+  }
+  return false;
+}
+export {
+  ApigeeLlm
+};

package/dist/esm/models/google_llm.js

@@ -8,6 +8,7 @@ import {
   FinishReason,
   GoogleGenAI
 } from "@google/genai";
+import { getBooleanEnvVar, isBrowser } from "../utils/env_aware_utils.js";
 import { logger } from "../utils/logger.js";
 import { GoogleLLMVariant } from "../utils/variant_utils.js";
 import { BaseLlm } from "./base_llm.js";
@@ -29,45 +30,23 @@ class Gemini extends BaseLlm {
       model = "gemini-2.5-flash";
     }
     super({ model });
-    this.project = project;
-    this.location = location;
-    this.apiKey = apiKey;
-    this.headers = headers;
-    const canReadEnv = typeof process === "object";
-    this.vertexai = !!vertexai;
-    if (!this.vertexai && canReadEnv) {
-      const vertexAIfromEnv = process.env["GOOGLE_GENAI_USE_VERTEXAI"];
-      if (vertexAIfromEnv) {
-        this.vertexai = vertexAIfromEnv.toLowerCase() === "true" || vertexAIfromEnv === "1";
-      }
-    }
-    if (this.vertexai) {
-      if (canReadEnv && !this.project) {
-        this.project = process.env["GOOGLE_CLOUD_PROJECT"];
-      }
-      if (canReadEnv && !this.location) {
-        this.location = process.env["GOOGLE_CLOUD_LOCATION"];
-      }
-      if (!this.project) {
-        throw new Error(
-          "VertexAI project must be provided via constructor or GOOGLE_CLOUD_PROJECT environment variable."
-        );
-      }
-      if (!this.location) {
-        throw new Error(
-          "VertexAI location must be provided via constructor or GOOGLE_CLOUD_LOCATION environment variable."
-        );
-      }
-    } else {
-      if (!this.apiKey && canReadEnv) {
-        this.apiKey = process.env["GOOGLE_GENAI_API_KEY"] || process.env["GEMINI_API_KEY"];
-      }
-      if (!this.apiKey) {
-        throw new Error(
-          "API key must be provided via constructor or GOOGLE_GENAI_API_KEY or GEMINI_API_KEY environment variable."
-        );
-      }
+    const params = geminiInitParams({
+      model,
+      vertexai,
+      project,
+      location,
+      apiKey
+    });
+    if (!params.vertexai && !params.apiKey) {
+      throw new Error(
+        "API key must be provided via constructor or GOOGLE_GENAI_API_KEY or GEMINI_API_KEY environment variable."
+      );
     }
+    this.project = params.project;
+    this.location = params.location;
+    this.apiKey = params.apiKey;
+    this.headers = headers;
+    this.vertexai = !!params.vertexai;
   }
   /**
    * Sends a request to the Gemini model.
@@ -156,25 +135,24 @@ class Gemini extends BaseLlm {
       yield createLlmResponse(response);
     }
   }
+  getHttpOptions() {
+    return { headers: { ...this.trackingHeaders, ...this.headers } };
+  }
   get apiClient() {
     if (this._apiClient) {
       return this._apiClient;
     }
-    const combinedHeaders = {
-      ...this.trackingHeaders,
-      ...this.headers
-    };
     if (this.vertexai) {
       this._apiClient = new GoogleGenAI({
         vertexai: this.vertexai,
         project: this.project,
         location: this.location,
-        httpOptions: { headers: combinedHeaders }
+        httpOptions: this.getHttpOptions()
       });
     } else {
       this._apiClient = new GoogleGenAI({
         apiKey: this.apiKey,
-        httpOptions: { headers: combinedHeaders }
+        httpOptions: this.getHttpOptions()
       });
     }
     return this._apiClient;
@@ -191,14 +169,17 @@ class Gemini extends BaseLlm {
     }
     return this._liveApiVersion;
   }
+  getLiveHttpOptions() {
+    return {
+      headers: this.trackingHeaders,
+      apiVersion: this.liveApiVersion
+    };
+  }
   get liveApiClient() {
     if (!this._liveApiClient) {
       this._liveApiClient = new GoogleGenAI({
         apiKey: this.apiKey,
-        httpOptions: {
-          headers: this.trackingHeaders,
-          apiVersion: this.liveApiVersion
-        }
+        httpOptions: this.getLiveHttpOptions()
       });
     }
     return this._liveApiClient;
@@ -276,6 +257,43 @@ function removeDisplayNameIfPresent(dataObj) {
     dataObj.displayName = void 0;
   }
 }
+function geminiInitParams({
+  model,
+  vertexai,
+  project,
+  location,
+  apiKey
+}) {
+  const params = { model, vertexai, project, location, apiKey };
+  params.vertexai = !!vertexai;
+  if (!params.vertexai && !isBrowser()) {
+    params.vertexai = getBooleanEnvVar("GOOGLE_GENAI_USE_VERTEXAI");
+  }
+  if (params.vertexai) {
+    if (!isBrowser() && !params.project) {
+      params.project = process.env["GOOGLE_CLOUD_PROJECT"];
+    }
+    if (!isBrowser() && !params.location) {
+      params.location = process.env["GOOGLE_CLOUD_LOCATION"];
+    }
+    if (!params.project) {
+      throw new Error(
+        "VertexAI project must be provided via constructor or GOOGLE_CLOUD_PROJECT environment variable."
+      );
+    }
+    if (!params.location) {
+      throw new Error(
+        "VertexAI location must be provided via constructor or GOOGLE_CLOUD_LOCATION environment variable."
+      );
+    }
+  } else {
+    if (!params.apiKey && !isBrowser()) {
+      params.apiKey = process.env["GOOGLE_GENAI_API_KEY"] || process.env["GEMINI_API_KEY"];
+    }
+  }
+  return params;
+}
 export {
-  Gemini
+  Gemini,
+  geminiInitParams
 };

package/dist/esm/models/registry.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { logger } from "../utils/logger.js";
+import { ApigeeLlm } from "./apigee_llm.js";
 import { Gemini } from "./google_llm.js";
 class LRUCache {
   constructor(maxSize) {
@@ -86,6 +87,7 @@ _LLMRegistry.llmRegistryDict = /* @__PURE__ */ new Map();
 _LLMRegistry.resolveCache = new LRUCache(32);
 let LLMRegistry = _LLMRegistry;
 LLMRegistry.register(Gemini);
+LLMRegistry.register(ApigeeLlm);
 export {
   LLMRegistry
 };

package/dist/esm/runner/runner.js

@@ -35,6 +35,37 @@ class Runner {
     this.memoryService = input.memoryService;
     this.credentialService = input.credentialService;
   }
+  /**
+   * Runs the agent with a new, ephemeral session.
+   *
+   * @param params.userId The user ID of the session.
+   * @param params.newMessage A new message to append to the session.
+   * @param params.stateDelta An optional state delta to apply to the session.
+   * @param params.runConfig The run config for the agent.
+   * @yields The Events generated by the agent.
+   */
+  async *runEphemeral(params) {
+    const session = await this.sessionService.createSession({
+      appName: this.appName,
+      userId: params.userId
+    });
+    const sessionId = session.id;
+    try {
+      yield* this.runAsync({
+        userId: params.userId,
+        sessionId,
+        newMessage: params.newMessage,
+        stateDelta: params.stateDelta,
+        runConfig: params.runConfig
+      });
+    } finally {
+      await this.sessionService.deleteSession({
+        appName: this.appName,
+        userId: params.userId,
+        sessionId
+      });
+    }
+  }
   /**
    * Runs the agent with the given message, and returns an async generator of
    * events.

package/dist/esm/sessions/base_session_service.js

@@ -3,8 +3,29 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { cloneDeep } from "lodash-es";
 import { State } from "./state.js";
 class BaseSessionService {
+  /**
+   * Gets a session or creates one if it doesn't exist.
+   *
+   * @param request The request to get or create a session.
+   * @return A promise that resolves to the session instance.
+   */
+  async getOrCreateSession(request) {
+    if (!request.sessionId) {
+      return this.createSession(request);
+    }
+    const session = await this.getSession({
+      appName: request.appName,
+      userId: request.userId,
+      sessionId: request.sessionId
+    });
+    if (session) {
+      return session;
+    }
+    return this.createSession(request);
+  }
   /**
    * Appends an event to a session.
    *
@@ -15,6 +36,7 @@ class BaseSessionService {
     if (event.partial) {
       return event;
     }
+    event = trimTempDeltaState(event);
     this.updateSessionState({ session, event });
     session.events.push(event);
     return event;
@@ -36,6 +58,32 @@ class BaseSessionService {
     }
   }
 }
+function trimTempDeltaState(event) {
+  if (!event.actions || !event.actions.stateDelta) {
+    return event;
+  }
+  const stateDelta = event.actions.stateDelta;
+  const filteredStateDelta = {};
+  for (const [key, value] of Object.entries(stateDelta)) {
+    if (!key.startsWith(State.TEMP_PREFIX)) {
+      filteredStateDelta[key] = value;
+    }
+  }
+  event.actions.stateDelta = filteredStateDelta;
+  return event;
+}
+function mergeStates(appState = {}, userState = {}, sessionState = {}) {
+  const merged = cloneDeep(sessionState);
+  for (const [k, v] of Object.entries(appState)) {
+    merged[State.APP_PREFIX + k] = v;
+  }
+  for (const [k, v] of Object.entries(userState)) {
+    merged[State.USER_PREFIX + k] = v;
+  }
+  return merged;
+}
 export {
-  BaseSessionService
+  BaseSessionService,
+  mergeStates,
+  trimTempDeltaState
 };