@google/adk 1.1.0 → 1.3.0

package/dist/esm/memory/vertex_ai_memory_bank_service.js

@@ -0,0 +1,468 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Client } from "@google-cloud/vertexai";
+import { createUserContent } from "@google/genai";
+import { logger } from "../utils/logger.js";
+import { getExpressModeApiKey } from "../utils/vertex_ai_utils.js";
+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) {
+    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 = getExpressModeApiKey(
+      options.projectId,
+      options.location,
+      options.expressModeApiKey
+    );
+    if (options.agentEngineId.includes("/")) {
+      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 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);
+    logger.debug("Search memory response received.");
+    const memoryEvents = [];
+    const retrievedMemories = retrievedMemoriesResponse.retrievedMemories || [];
+    for (const retrievedMemory of retrievedMemories) {
+      logger.debug(`Retrieved memory: ${JSON.stringify(retrievedMemory)}`);
+      if (retrievedMemory.memory && retrievedMemory.memory.fact) {
+        const content = 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);
+      logger.debug("Generate memory response received.");
+      logger.debug(`Generate memory response: ${JSON.stringify(operation)}`);
+    } else {
+      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);
+      logger.info("Create memory response received.");
+      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);
+      logger.info("Generate direct memory response received.");
+      logger.debug(
+        `Generate direct memory response: ${JSON.stringify(operation)}`
+      );
+    }
+  }
+}
+function buildCreateMemoryConfig(params) {
+  const config = { waitForCompletion: false };
+  if (params.customMetadata) {
+    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 {
+        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)) {
+    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") {
+      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;
+  }
+  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 {
+        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;
+}
+export {
+  VertexAiMemoryBankService
+};

package/dist/esm/models/gemini_llm_connection.js

@@ -2,13 +2,17 @@ import {createRequire as topLevelCreateRequire} from 'module';
 const require = topLevelCreateRequire(import.meta.url);
 /**
  * @license
- * Copyright 2025 Google LLC
+ * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { LiveResponseAggregator } from "../utils/live_connection_utils.js";
 import { logger } from "../utils/logger.js";
+import { isGemini3xFlashLive } from "../utils/model_name.js";
 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.
@@ -27,9 +31,10 @@ class GeminiLlmConnection {
       }
     );
     if (contents.length > 0) {
+      const isGemini3x = 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 {
       logger.info("no content is sent");
@@ -56,10 +61,16 @@ class GeminiLlmConnection {
       });
     } else {
       logger.debug("Sending LLM new content", content);
-      this.geminiSession.sendClientContent({
-        turns: [content],
-        turnComplete: true
-      });
+      const isGemini3x = isGemini3xFlashLive(this.modelVersion);
+      if (isGemini3x && content.parts.length === 1 && content.parts[0].text) {
+        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
+        });
+      }
     }
   }
   /**
@@ -68,8 +79,36 @@ class GeminiLlmConnection {
    * @param blob The blob to send to the model.
    */
   async sendRealtime(blob) {
+    var _a, _b, _c;
     logger.debug("Sending LLM Blob:", blob);
-    this.geminiSession.sendRealtimeInput({ media: blob });
+    const isGemini3x = 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 {
+        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.
@@ -78,20 +117,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 LiveResponseAggregator(this.modelVersion);
+    for await (const message of this.messageQueue) {
+      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/esm/models/google_llm.js

@@ -12,6 +12,7 @@ import {
 import { getBooleanEnvVar, isBrowser } from "../utils/env_aware_utils.js";
 import { logger } from "../utils/logger.js";
 import { GoogleLLMVariant } from "../utils/variant_utils.js";
+import { AsyncQueue } from "../utils/async_queue.js";
 import { StreamingResponseAggregator } from "../utils/streaming_utils.js";
 import { BaseLlm } from "./base_llm.js";
 import { GeminiLlmConnection } from "./gemini_llm_connection.js";
@@ -143,10 +144,19 @@ class Gemini extends BaseLlm {
   }
   get liveApiClient() {
     if (!this._liveApiClient) {
-      this._liveApiClient = new GoogleGenAI({
-        apiKey: this.apiKey,
-        httpOptions: this.getLiveHttpOptions()
-      });
+      if (this.vertexai) {
+        this._liveApiClient = new GoogleGenAI({
+          vertexai: this.vertexai,
+          project: this.project,
+          location: this.location || "global",
+          httpOptions: this.getLiveHttpOptions()
+        });
+      } else {
+        this._liveApiClient = new GoogleGenAI({
+          apiKey: this.apiKey,
+          httpOptions: this.getLiveHttpOptions()
+        });
+      }
     }
     return this._liveApiClient;
   }
@@ -178,16 +188,24 @@ class Gemini extends BaseLlm {
       };
     }
     llmRequest.liveConnectConfig.tools = (_c = llmRequest.config) == null ? void 0 : _c.tools;
+    const modelVersion = (_d = llmRequest.model) != null ? _d : this.model;
+    const messageQueue = new 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 GeminiLlmConnection(liveSession);
+    return new GeminiLlmConnection(liveSession, modelVersion, messageQueue);
   }
   preprocessRequest(llmRequest) {
     if (this.apiBackend === GoogleLLMVariant.GEMINI_API) {

package/dist/esm/plugins/security_plugin.js

@@ -16,6 +16,11 @@ var PolicyOutcome = /* @__PURE__ */ ((PolicyOutcome2) => {
   return PolicyOutcome2;
 })(PolicyOutcome || {});
 class InMemoryPolicyEngine {
+  /**
+   * Always returns {@link PolicyOutcome.ALLOW} for every tool call.
+   *
+   * @returns A promise resolving to an ALLOW result.
+   */
   async evaluate() {
     return Promise.resolve({
       outcome: "ALLOW" /* ALLOW */,
@@ -24,11 +29,22 @@ class InMemoryPolicyEngine {
   }
 }
 class SecurityPlugin extends BasePlugin {
+  /**
+   * @param params - Optional configuration. Defaults to {@link InMemoryPolicyEngine}
+   *   when no policy engine is provided.
+   */
   constructor(params) {
     var _a;
     super("security_plugin");
     this.policyEngine = (_a = params == null ? void 0 : params.policyEngine) != null ? _a : new InMemoryPolicyEngine();
   }
+  /**
+   * Intercepts tool calls, evaluating them against the policy engine before
+   * execution and handling confirmation flows for calls that require it.
+   *
+   * @returns A partial or error response object if the call is blocked or
+   *   awaiting confirmation, or `undefined` to allow execution to proceed.
+   */
   async beforeToolCallback({
     tool,
     toolArgs,