@google/adk 0.3.0 → 0.5.0

package/dist/web/models/apigee_llm.js

@@ -0,0 +1,219 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __await = function(promise, isYieldStar) {
+  this[0] = promise;
+  this[1] = isYieldStar;
+};
+var __asyncGenerator = (__this, __arguments, generator) => {
+  var resume = (k, v, yes, no) => {
+    try {
+      var x = generator[k](v), isAwait = (v = x.value) instanceof __await, done = x.done;
+      Promise.resolve(isAwait ? v[0] : v).then((y) => isAwait ? resume(k === "return" ? k : "next", v[1] ? { done: y.done, value: y.value } : y, yes, no) : yes({ value: y, done })).catch((e) => resume("throw", e, yes, no));
+    } catch (e) {
+      no(e);
+    }
+  }, method = (k) => it[k] = (x) => new Promise((yes, no) => resume(k, x, yes, no)), it = {};
+  return generator = generator.apply(__this, __arguments), it[__knownSymbol("asyncIterator")] = () => it, method("next"), method("throw"), method("return"), it;
+};
+var __yieldStar = (value) => {
+  var obj = value[__knownSymbol("asyncIterator")], isAwait = false, method, it = {};
+  if (obj == null) {
+    obj = value[__knownSymbol("iterator")]();
+    method = (k) => it[k] = (x) => obj[k](x);
+  } else {
+    obj = obj.call(value);
+    method = (k) => it[k] = (v) => {
+      if (isAwait) {
+        isAwait = false;
+        if (k === "throw") throw v;
+        return v;
+      }
+      isAwait = true;
+      return {
+        done: false,
+        value: new __await(new Promise((resolve) => {
+          var x = obj[k](v);
+          if (!(x instanceof Object)) __typeError("Object expected");
+          resolve(x);
+        }), 1)
+      };
+    };
+  }
+  return it[__knownSymbol("iterator")] = () => it, method("next"), "throw" in obj ? method("throw") : it.throw = (x) => {
+    throw x;
+  }, "return" in obj && method("return"), it;
+};
+/**
+ * @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 ".concat(model, " is not a valid Apigee model, expected apigee/[<provider>/][<version>/]<model_id>")
+      );
+    }
+    super(__spreadProps(__spreadValues({}, 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 ".concat(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;
+  }
+  generateContentAsync(llmRequest, stream = false) {
+    return __asyncGenerator(this, null, function* () {
+      var _a;
+      const modelToUse = (_a = llmRequest.model) != null ? _a : this.model;
+      llmRequest.model = getModelId(modelToUse);
+      yield* __yieldStar(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 ".concat(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/web/models/google_llm.js

@@ -41,6 +41,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";
@@ -62,45 +63,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.
@@ -200,22 +179,24 @@ class Gemini extends BaseLlm {
       }
     });
   }
+  getHttpOptions() {
+    return { headers: __spreadValues(__spreadValues({}, this.trackingHeaders), this.headers) };
+  }
   get apiClient() {
     if (this._apiClient) {
       return this._apiClient;
     }
-    const combinedHeaders = __spreadValues(__spreadValues({}, 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;
@@ -232,14 +213,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;
@@ -317,6 +301,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/web/models/llm_response.js

@@ -12,6 +12,7 @@ function createLlmResponse(response) {
       return {
         content: candidate.content,
         groundingMetadata: candidate.groundingMetadata,
+        citationMetadata: candidate.citationMetadata,
         usageMetadata,
         finishReason: candidate.finishReason
       };
@@ -20,6 +21,7 @@ function createLlmResponse(response) {
       errorCode: candidate.finishReason,
       errorMessage: candidate.finishMessage,
       usageMetadata,
+      citationMetadata: candidate.citationMetadata,
       finishReason: candidate.finishReason
     };
   }

package/dist/web/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/web/plugins/base_plugin.js

@@ -198,7 +198,7 @@ class BasePlugin {
      * Callback executed when a tool call encounters an error.
       tool: BaseTool;
       toolArgs: Record<string, unknown>;
-      toolContext: ToolContext;
+      toolContext: Context;
       result: Record<string, unknown>;
     }): Promise<Record<string, unknown> | undefined> {
       return;

package/dist/web/runner/runner.js

@@ -83,6 +83,39 @@ 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.
+   */
+  runEphemeral(params) {
+    return __asyncGenerator(this, null, function* () {
+      const session = yield new __await(this.sessionService.createSession({
+        appName: this.appName,
+        userId: params.userId
+      }));
+      const sessionId = session.id;
+      try {
+        yield* __yieldStar(this.runAsync({
+          userId: params.userId,
+          sessionId,
+          newMessage: params.newMessage,
+          stateDelta: params.stateDelta,
+          runConfig: params.runConfig
+        }));
+      } finally {
+        yield new __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.
@@ -277,7 +310,7 @@ class Runner {
       return rootAgent.findAgent(event.author) || rootAgent;
     }
     for (let i = session.events.length - 1; i >= 0; i--) {
-      logger.info("event: ", JSON.stringify(session.events[i]));
+      logger.info("event:", JSON.stringify(session.events[i]));
       const event2 = session.events[i];
       if (event2.author === "user" || !event2.author) {
         continue;

package/dist/web/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
 };