@google/adk 1.1.0 → 1.3.0

package/dist/cjs/memory/vertex_ai_memory_bank_service.js

@@ -0,0 +1,496 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var vertex_ai_memory_bank_service_exports = {};
+__export(vertex_ai_memory_bank_service_exports, {
+  VertexAiMemoryBankService: () => VertexAiMemoryBankService
+});
+module.exports = __toCommonJS(vertex_ai_memory_bank_service_exports);
+var import_vertexai = require("@google-cloud/vertexai");
+var import_genai = require("@google/genai");
+var import_logger = require("../utils/logger.js");
+var import_vertex_ai_utils = require("../utils/vertex_ai_utils.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const GENERATE_MEMORIES_KNOWN_FIELDS = [
+  "disableConsolidation",
+  "waitForCompletion",
+  "revisionLabels",
+  "revisionExpireTime",
+  "revisionTtl",
+  "disableMemoryRevisions",
+  "metadataMergeStrategy",
+  "allowedTopics"
+];
+const CREATE_MEMORY_KNOWN_FIELDS = [
+  "displayName",
+  "description",
+  "waitForCompletion",
+  "ttl",
+  "expireTime",
+  "revisionExpireTime",
+  "revisionTtl",
+  "disableMemoryRevisions",
+  "topics",
+  "memoryId"
+];
+const ENABLE_CONSOLIDATION_KEY = "enable_consolidation";
+const MAX_DIRECT_MEMORIES_PER_GENERATE_CALL = 5;
+function shouldFilterOutEvent(content) {
+  return !((content == null ? void 0 : content.parts) || []).some(
+    (p) => p.text || p.inlineData || p.fileData
+  );
+}
+function toVertexMetadataValue(key, value) {
+  if (typeof value === "boolean") {
+    return { boolValue: value };
+  }
+  if (typeof value === "number") {
+    return { doubleValue: value };
+  }
+  if (typeof value === "string") {
+    return { stringValue: value };
+  }
+  if (value instanceof Date) {
+    return { timestampValue: value.toISOString() };
+  }
+  if (typeof value === "object" && value !== null) {
+    const v = value;
+    if (v.boolValue !== void 0 || v.doubleValue !== void 0 || v.stringValue !== void 0 || v.timestampValue !== void 0) {
+      return v;
+    }
+    return { stringValue: JSON.stringify(value) };
+  }
+  if (value === null || value === void 0) {
+    import_logger.logger.warn(
+      `Ignoring custom metadata key ${key} because its value is null or undefined.`
+    );
+    return void 0;
+  }
+  return { stringValue: String(value) };
+}
+class VertexAiMemoryBankService {
+  constructor(options) {
+    if (!options.agentEngineId) {
+      throw new Error(
+        "agentEngineId is required for VertexAiMemoryBankService."
+      );
+    }
+    this.projectId = options.projectId;
+    this.location = options.location;
+    this.agentEngineId = options.agentEngineId;
+    this.expressModeApiKey = (0, import_vertex_ai_utils.getExpressModeApiKey)(
+      options.projectId,
+      options.location,
+      options.expressModeApiKey
+    );
+    if (options.agentEngineId.includes("/")) {
+      import_logger.logger.warn(
+        `agentEngineId appears to be a full resource path: '${options.agentEngineId}'. Expected just the ID (e.g., '456'). Extract the ID using: agentEngine.apiResource.name.split('/').pop()`
+      );
+    }
+    if (options.client) {
+      this.memories = options.client.agentEnginesInternal.memories;
+    } else {
+      const client = new import_vertexai.Client({
+        project: this.projectId,
+        location: this.location
+      });
+      this.memories = client.agentEnginesInternal.memories;
+    }
+  }
+  async addSessionToMemory(session) {
+    await this.addEventsToMemoryFromEvents({
+      appName: session.appName,
+      userId: session.userId,
+      eventsToProcess: session.events
+    });
+  }
+  /**
+   * Adds events to Vertex AI Memory Bank via memories.generate.
+   */
+  async addEventsToMemory(request) {
+    await this.addEventsToMemoryFromEvents({
+      appName: request.appName,
+      userId: request.userId,
+      eventsToProcess: request.events,
+      customMetadata: request.customMetadata
+    });
+  }
+  /**
+   * Adds explicit memory items using Vertex Memory Bank.
+   */
+  async addMemory(request) {
+    if (isConsolidationEnabled(request.customMetadata)) {
+      return this.addMemoriesViaGenerateDirectMemoriesSource(request);
+    }
+    await this.addMemoriesViaCreate(request);
+  }
+  async searchMemory(request) {
+    const params = {
+      name: `reasoningEngines/${this.agentEngineId}`,
+      scope: {
+        app_name: request.appName,
+        user_id: request.userId
+      },
+      similaritySearchParams: {
+        searchQuery: request.query
+      }
+    };
+    const retrievedMemoriesResponse = await this.memories.retrieveInternal(params);
+    import_logger.logger.debug("Search memory response received.");
+    const memoryEvents = [];
+    const retrievedMemories = retrievedMemoriesResponse.retrievedMemories || [];
+    for (const retrievedMemory of retrievedMemories) {
+      import_logger.logger.debug(`Retrieved memory: ${JSON.stringify(retrievedMemory)}`);
+      if (retrievedMemory.memory && retrievedMemory.memory.fact) {
+        const content = (0, import_genai.createUserContent)(retrievedMemory.memory.fact);
+        memoryEvents.push({
+          author: "user",
+          content,
+          timestamp: retrievedMemory.memory.updateTime
+        });
+      }
+    }
+    return { memories: memoryEvents };
+  }
+  async addEventsToMemoryFromEvents(request) {
+    const directEvents = [];
+    for (const event of request.eventsToProcess) {
+      if (shouldFilterOutEvent(event.content)) {
+        continue;
+      }
+      directEvents.push({
+        content: JSON.parse(JSON.stringify(event.content))
+      });
+    }
+    if (directEvents.length > 0) {
+      const config = buildGenerateMemoriesConfig(request.customMetadata);
+      const params = {
+        name: `reasoningEngines/${this.agentEngineId}`,
+        directContentsSource: { events: directEvents },
+        scope: {
+          app_name: request.appName,
+          user_id: request.userId
+        },
+        config
+      };
+      const operation = await this.memories.generateInternal(params);
+      import_logger.logger.debug("Generate memory response received.");
+      import_logger.logger.debug(`Generate memory response: ${JSON.stringify(operation)}`);
+    } else {
+      import_logger.logger.info("No events to add to memory.");
+    }
+  }
+  async addMemoriesViaCreate(request) {
+    const validatedMemories = normalizeMemoriesForCreate(request.memories);
+    for (let index = 0; index < validatedMemories.length; index++) {
+      const memory = validatedMemories[index];
+      const memoryFact = memoryEntryToFact(memory, index);
+      const memoryMetadata = mergeCustomMetadataForMemory({
+        customMetadata: request.customMetadata,
+        memory
+      });
+      const memoryRevisionLabels = revisionLabelsForMemory(memory);
+      const config = buildCreateMemoryConfig({
+        customMetadata: memoryMetadata,
+        memoryRevisionLabels
+      });
+      const params = {
+        name: `reasoningEngines/${this.agentEngineId}`,
+        fact: memoryFact,
+        scope: {
+          app_name: request.appName,
+          user_id: request.userId
+        },
+        config
+      };
+      const operation = await this.memories.createInternal(params);
+      import_logger.logger.info("Create memory response received.");
+      import_logger.logger.debug(`Create memory response: ${JSON.stringify(operation)}`);
+    }
+  }
+  async addMemoriesViaGenerateDirectMemoriesSource(request) {
+    const validatedMemories = normalizeMemoriesForCreate(request.memories);
+    const memoryTexts = validatedMemories.map(
+      (m, i) => memoryEntryToFact(m, i)
+    );
+    const config = buildGenerateMemoriesConfig(request.customMetadata);
+    const memoryBatches = iterMemoryBatches(memoryTexts);
+    for (const memoryBatch of memoryBatches) {
+      const params = {
+        name: `reasoningEngines/${this.agentEngineId}`,
+        directMemoriesSource: {
+          directMemories: memoryBatch.map((fact) => ({ fact }))
+        },
+        scope: {
+          app_name: request.appName,
+          user_id: request.userId
+        },
+        config
+      };
+      const operation = await this.memories.generateInternal(params);
+      import_logger.logger.info("Generate direct memory response received.");
+      import_logger.logger.debug(
+        `Generate direct memory response: ${JSON.stringify(operation)}`
+      );
+    }
+  }
+}
+function buildCreateMemoryConfig(params) {
+  const config = { waitForCompletion: false };
+  if (params.customMetadata) {
+    import_logger.logger.debug(
+      `Memory creation metadata: ${JSON.stringify(params.customMetadata)}`
+    );
+  }
+  const metadataByKey = {};
+  const customRevisionLabels = {};
+  for (const [key, value] of Object.entries(params.customMetadata || {})) {
+    if (key === ENABLE_CONSOLIDATION_KEY) {
+      continue;
+    }
+    if (key === "metadata") {
+      if (value === null || value === void 0) continue;
+      if (typeof value === "object" && !Array.isArray(value)) {
+        config["metadata"] = buildVertexMetadata(
+          value
+        );
+      } else {
+        import_logger.logger.warn(
+          'Ignoring metadata because customMetadata["metadata"] is not an object.'
+        );
+      }
+      continue;
+    }
+    if (key === "revisionLabels") {
+      if (value === null || value === void 0) continue;
+      const extractedLabels = extractRevisionLabels(
+        value,
+        'customMetadata["revisionLabels"]'
+      );
+      if (extractedLabels) {
+        Object.assign(customRevisionLabels, extractedLabels);
+      }
+      continue;
+    }
+    if (CREATE_MEMORY_KNOWN_FIELDS.includes(key)) {
+      if (value !== null && value !== void 0) {
+        config[key] = value;
+      }
+    } else {
+      metadataByKey[key] = value;
+    }
+  }
+  if (Object.keys(metadataByKey).length > 0) {
+    const existingMetadata = config["metadata"];
+    if (!existingMetadata) {
+      config["metadata"] = buildVertexMetadata(metadataByKey);
+    } else {
+      config["metadata"] = {
+        ...existingMetadata,
+        ...buildVertexMetadata(metadataByKey)
+      };
+    }
+  }
+  const revisionLabels = {
+    ...customRevisionLabels,
+    ...params.memoryRevisionLabels
+  };
+  if (Object.keys(revisionLabels).length > 0) {
+    config["revisionLabels"] = revisionLabels;
+  }
+  return config;
+}
+function extractRevisionLabels(value, source) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    import_logger.logger.warn(`Ignoring ${source} because it is not an object.`);
+    return void 0;
+  }
+  const revisionLabels = {};
+  for (const [key, labelValue] of Object.entries(value)) {
+    if (typeof labelValue !== "string") {
+      import_logger.logger.warn(
+        `Ignoring revision label ${key} from ${source} because its value is not a string.`
+      );
+      continue;
+    }
+    revisionLabels[key] = labelValue;
+  }
+  if (Object.keys(revisionLabels).length === 0) {
+    return void 0;
+  }
+  return revisionLabels;
+}
+function buildVertexMetadata(metadataByKey) {
+  const vertexMetadata = {};
+  for (const [key, value] of Object.entries(metadataByKey)) {
+    const convertedValue = toVertexMetadataValue(key, value);
+    if (convertedValue !== void 0) {
+      vertexMetadata[key] = convertedValue;
+    }
+  }
+  return vertexMetadata;
+}
+function buildGenerateMemoriesConfig(customMetadata) {
+  const config = { waitForCompletion: false };
+  if (!customMetadata) {
+    return config;
+  }
+  import_logger.logger.debug(`Memory generation metadata: ${JSON.stringify(customMetadata)}`);
+  const metadataByKey = {};
+  for (const [key, value] of Object.entries(customMetadata)) {
+    if (key === ENABLE_CONSOLIDATION_KEY) {
+      continue;
+    }
+    if (key === "ttl") {
+      if (value === null || value === void 0) continue;
+      if (customMetadata["revisionTtl"] === void 0) {
+        config["revisionTtl"] = value;
+      }
+      continue;
+    }
+    if (key === "metadata") {
+      if (value === null || value === void 0) continue;
+      if (typeof value === "object" && !Array.isArray(value)) {
+        config["metadata"] = buildVertexMetadata(
+          value
+        );
+      } else {
+        import_logger.logger.warn(
+          'Ignoring metadata because customMetadata["metadata"] is not an object.'
+        );
+      }
+      continue;
+    }
+    if (GENERATE_MEMORIES_KNOWN_FIELDS.includes(key)) {
+      if (value !== null && value !== void 0) {
+        config[key] = value;
+      }
+    } else {
+      metadataByKey[key] = value;
+    }
+  }
+  if (Object.keys(metadataByKey).length > 0) {
+    const existingMetadata = config["metadata"];
+    if (!existingMetadata) {
+      config["metadata"] = buildVertexMetadata(metadataByKey);
+    } else {
+      config["metadata"] = {
+        ...existingMetadata,
+        ...buildVertexMetadata(metadataByKey)
+      };
+    }
+  }
+  return config;
+}
+function normalizeMemoriesForCreate(memories) {
+  if (!Array.isArray(memories)) {
+    throw new TypeError("memories must be a sequence of memory items.");
+  }
+  if (memories.length === 0) {
+    throw new Error("memories must contain at least one entry.");
+  }
+  return memories;
+}
+function memoryEntryToFact(memory, index) {
+  const textParts = [];
+  if (memory.content && memory.content.parts) {
+    for (const part of memory.content.parts) {
+      if (part.inlineData || part.fileData) {
+        throw new Error(
+          `memories[${index}] must include text only; inlineData and fileData are not supported.`
+        );
+      }
+      if (part.text) {
+        const strippedText = part.text.trim();
+        if (strippedText) {
+          textParts.push(strippedText);
+        }
+      }
+    }
+  }
+  if (textParts.length === 0) {
+    throw new Error(`memories[${index}] must include non-whitespace text.`);
+  }
+  return textParts.join("\n");
+}
+function mergeCustomMetadataForMemory(params) {
+  const mergedMetadata = {};
+  if (params.customMetadata) {
+    Object.assign(mergedMetadata, params.customMetadata);
+  }
+  const memoryWithMetadata = params.memory;
+  if (memoryWithMetadata.customMetadata) {
+    Object.assign(mergedMetadata, memoryWithMetadata.customMetadata);
+  }
+  if (Object.keys(mergedMetadata).length === 0) {
+    return void 0;
+  }
+  return mergedMetadata;
+}
+function revisionLabelsForMemory(memory) {
+  const revisionLabels = {};
+  if (memory.author) {
+    revisionLabels["author"] = memory.author;
+  }
+  if (memory.timestamp) {
+    revisionLabels["timestamp"] = memory.timestamp;
+  }
+  if (Object.keys(revisionLabels).length === 0) {
+    return void 0;
+  }
+  return revisionLabels;
+}
+function isConsolidationEnabled(customMetadata) {
+  if (!customMetadata) {
+    return false;
+  }
+  const enableConsolidation = customMetadata[ENABLE_CONSOLIDATION_KEY];
+  if (enableConsolidation === void 0) {
+    return false;
+  }
+  if (typeof enableConsolidation !== "boolean") {
+    throw new TypeError(
+      `customMetadata["${ENABLE_CONSOLIDATION_KEY}"] must be a bool.`
+    );
+  }
+  return enableConsolidation;
+}
+function iterMemoryBatches(memories) {
+  const memoryBatches = [];
+  for (let index = 0; index < memories.length; index += MAX_DIRECT_MEMORIES_PER_GENERATE_CALL) {
+    memoryBatches.push(
+      memories.slice(index, index + MAX_DIRECT_MEMORIES_PER_GENERATE_CALL)
+    );
+  }
+  return memoryBatches;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VertexAiMemoryBankService
+});

package/dist/cjs/models/gemini_llm_connection.js

@@ -27,15 +27,19 @@ __export(gemini_llm_connection_exports, {
   GeminiLlmConnection: () => GeminiLlmConnection
 });
 module.exports = __toCommonJS(gemini_llm_connection_exports);
+var import_live_connection_utils = require("../utils/live_connection_utils.js");
 var import_logger = require("../utils/logger.js");
+var import_model_name = require("../utils/model_name.js");
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
 class GeminiLlmConnection {
-  constructor(geminiSession) {
+  constructor(geminiSession, modelVersion, messageQueue) {
     this.geminiSession = geminiSession;
+    this.modelVersion = modelVersion;
+    this.messageQueue = messageQueue;
   }
   /**
    * Sends the conversation history to the gemini model.
@@ -54,9 +58,10 @@ class GeminiLlmConnection {
       }
     );
     if (contents.length > 0) {
+      const isGemini3x = (0, import_model_name.isGemini3xFlashLive)(this.modelVersion);
       this.geminiSession.sendClientContent({
         turns: contents,
-        turnComplete: contents[contents.length - 1].role === "user"
+        turnComplete: isGemini3x ? true : contents[contents.length - 1].role === "user"
       });
     } else {
       import_logger.logger.info("no content is sent");
@@ -83,10 +88,16 @@ class GeminiLlmConnection {
       });
     } else {
       import_logger.logger.debug("Sending LLM new content", content);
-      this.geminiSession.sendClientContent({
-        turns: [content],
-        turnComplete: true
-      });
+      const isGemini3x = (0, import_model_name.isGemini3xFlashLive)(this.modelVersion);
+      if (isGemini3x && content.parts.length === 1 && content.parts[0].text) {
+        import_logger.logger.debug("Using sendRealtimeInput for Gemini 3.x text input");
+        this.geminiSession.sendRealtimeInput({ text: content.parts[0].text });
+      } else {
+        this.geminiSession.sendClientContent({
+          turns: [content],
+          turnComplete: true
+        });
+      }
     }
   }
   /**
@@ -95,8 +106,36 @@ class GeminiLlmConnection {
    * @param blob The blob to send to the model.
    */
   async sendRealtime(blob) {
+    var _a, _b, _c;
     import_logger.logger.debug("Sending LLM Blob:", blob);
-    this.geminiSession.sendRealtimeInput({ media: blob });
+    const isGemini3x = (0, import_model_name.isGemini3xFlashLive)(this.modelVersion);
+    const isNativeAudio = (_a = this.modelVersion) == null ? void 0 : _a.includes("native-audio");
+    if (isGemini3x || isNativeAudio) {
+      if ((_b = blob.mimeType) == null ? void 0 : _b.startsWith("audio/")) {
+        this.geminiSession.sendRealtimeInput({ audio: blob });
+      } else if ((_c = blob.mimeType) == null ? void 0 : _c.startsWith("image/")) {
+        this.geminiSession.sendRealtimeInput({ video: blob });
+      } else {
+        import_logger.logger.warn(
+          "Blob not sent. Unknown or empty mime type for sendRealtimeInput:",
+          blob.mimeType
+        );
+      }
+    } else {
+      this.geminiSession.sendRealtimeInput({ media: blob });
+    }
+  }
+  /**
+   * Sends an activity start signal to the model.
+   */
+  async sendActivityStart() {
+    this.geminiSession.sendRealtimeInput({ activityStart: {} });
+  }
+  /**
+   * Sends an activity end signal to the model.
+   */
+  async sendActivityEnd() {
+    this.geminiSession.sendRealtimeInput({ activityEnd: {} });
   }
   /**
    * Builds a full text response.
@@ -105,20 +144,24 @@ class GeminiLlmConnection {
    * partial.
    *
    * @param text The text to be included in the response.
+   * @param isThought Whether the text is a thought.
+   * @param groundingMetadata The grounding metadata to include.
    * @returns An LlmResponse containing the full text.
    */
-  buildFullTextResponse(text) {
-    return {
-      content: {
-        role: "model",
-        parts: [{ text }]
-      }
-    };
-  }
-  // TODO(b/425992518): GenAI SDK inconsistent API, missing methods.
-  // eslint-disable-next-line require-yield
   async *receive() {
-    throw new Error("Not Implemented.");
+    if (!this.messageQueue) {
+      throw new Error("Message queue is not initialized.");
+    }
+    const aggregator = new import_live_connection_utils.LiveResponseAggregator(this.modelVersion);
+    for await (const message of this.messageQueue) {
+      import_logger.logger.debug("Got LLM Live message:", message);
+      for (const response of aggregator.processMessage(message)) {
+        yield response;
+      }
+    }
+    for (const response of aggregator.close()) {
+      yield response;
+    }
   }
   /**
    * Closes the llm server connection.

package/dist/cjs/models/google_llm.js

@@ -32,6 +32,7 @@ var import_genai = require("@google/genai");
 var import_env_aware_utils = require("../utils/env_aware_utils.js");
 var import_logger = require("../utils/logger.js");
 var import_variant_utils = require("../utils/variant_utils.js");
+var import_async_queue = require("../utils/async_queue.js");
 var import_streaming_utils = require("../utils/streaming_utils.js");
 var import_base_llm = require("./base_llm.js");
 var import_gemini_llm_connection = require("./gemini_llm_connection.js");
@@ -168,10 +169,19 @@ class Gemini extends import_base_llm.BaseLlm {
   }
   get liveApiClient() {
     if (!this._liveApiClient) {
-      this._liveApiClient = new import_genai.GoogleGenAI({
-        apiKey: this.apiKey,
-        httpOptions: this.getLiveHttpOptions()
-      });
+      if (this.vertexai) {
+        this._liveApiClient = new import_genai.GoogleGenAI({
+          vertexai: this.vertexai,
+          project: this.project,
+          location: this.location || "global",
+          httpOptions: this.getLiveHttpOptions()
+        });
+      } else {
+        this._liveApiClient = new import_genai.GoogleGenAI({
+          apiKey: this.apiKey,
+          httpOptions: this.getLiveHttpOptions()
+        });
+      }
     }
     return this._liveApiClient;
   }
@@ -203,16 +213,24 @@ class Gemini extends import_base_llm.BaseLlm {
       };
     }
     llmRequest.liveConnectConfig.tools = (_c = llmRequest.config) == null ? void 0 : _c.tools;
+    const modelVersion = (_d = llmRequest.model) != null ? _d : this.model;
+    const messageQueue = new import_async_queue.AsyncQueue();
     const liveSession = await this.liveApiClient.live.connect({
-      model: (_d = llmRequest.model) != null ? _d : this.model,
+      model: modelVersion,
       config: llmRequest.liveConnectConfig,
       callbacks: {
-        // TODO - b/425992518: GenAI SDK inconsistent API, missing methods.
-        onmessage: () => {
+        onmessage: (message) => {
+          messageQueue.push(message);
+        },
+        onerror: (error) => {
+          messageQueue.error(error);
+        },
+        onclose: () => {
+          messageQueue.close();
         }
       }
     });
-    return new import_gemini_llm_connection.GeminiLlmConnection(liveSession);
+    return new import_gemini_llm_connection.GeminiLlmConnection(liveSession, modelVersion, messageQueue);
   }
   preprocessRequest(llmRequest) {
     if (this.apiBackend === import_variant_utils.GoogleLLMVariant.GEMINI_API) {