@google/adk 1.1.0 → 1.2.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/runner/in_memory_runner.js

@@ -10,11 +10,16 @@ import { InMemoryMemoryService } from "../memory/in_memory_memory_service.js";
 import { InMemorySessionService } from "../sessions/in_memory_session_service.js";
 import { Runner } from "./runner.js";
 class InMemoryRunner extends Runner {
-  constructor({
-    agent,
-    appName = "InMemoryRunner",
-    plugins = []
-  }) {
+  /**
+   * Creates a new InMemoryRunner instance.
+   *
+   * @param params The configuration for the runner.
+   * @param params.agent The root agent to run.
+   * @param params.appName The application name. Defaults to `'InMemoryRunner'`.
+   * @param params.plugins An optional list of plugins.
+   */
+  constructor(params) {
+    const { agent, appName = "InMemoryRunner", plugins = [] } = params;
     super({
       appName,
       agent,

package/dist/esm/runner/runner.js

@@ -25,6 +25,7 @@ import {
   runAsyncGeneratorWithOtelContext,
   tracer
 } from "../telemetry/tracing.js";
+import { isBaseToolset } from "../tools/base_toolset.js";
 import { logger } from "../utils/logger.js";
 import { isGemini2OrAbove } from "../utils/model_name.js";
 const RUNNER_SIGNATURE_SYMBOL = Symbol.for("google.adk.runner");
@@ -33,6 +34,11 @@ function isRunner(obj) {
 }
 _a = RUNNER_SIGNATURE_SYMBOL;
 class Runner {
+  /**
+   * Creates a new Runner instance.
+   *
+   * @param input The configuration for the runner.
+   */
   constructor(input) {
     this[_a] = true;
     var _a2;
@@ -65,7 +71,8 @@ class Runner {
         sessionId,
         newMessage: params.newMessage,
         stateDelta: params.stateDelta,
-        runConfig: params.runConfig
+        runConfig: params.runConfig,
+        customMetadata: params.customMetadata
       });
     } finally {
       await this.sessionService.deleteSession({
@@ -170,7 +177,8 @@ class Runner {
                 invocationId: invocationContext.invocationId,
                 author: "user",
                 actions: stateDelta ? createEventActions({ stateDelta }) : void 0,
-                content: newMessage
+                content: newMessage,
+                customMetadata: params.customMetadata
               })
             });
             if ((_e = params.abortSignal) == null ? void 0 : _e.aborted) {
@@ -235,6 +243,8 @@ class Runner {
       );
     } finally {
       span.end();
+      const toolsets = getAllToolsets(this.agent);
+      await Promise.allSettled(toolsets.map((t) => t.close()));
     }
   }
   /**
@@ -354,6 +364,26 @@ function findEventByLastFunctionResponseId(events) {
   }
   return null;
 }
+function getAllToolsets(agent) {
+  const toolsets = [];
+  const visited = /* @__PURE__ */ new Set();
+  function traverse(curr) {
+    if (visited.has(curr)) return;
+    visited.add(curr);
+    if (isLlmAgent(curr)) {
+      for (const tool of curr.tools) {
+        if (isBaseToolset(tool)) {
+          toolsets.push(tool);
+        }
+      }
+    }
+    for (const sub of curr.subAgents) {
+      traverse(sub);
+    }
+  }
+  traverse(agent);
+  return toolsets;
+}
 export {
   Runner,
   isRunner

package/dist/esm/sessions/database_session_service.js

@@ -193,7 +193,11 @@ class DatabaseSessionService extends BaseSessionService {
   }
   async listSessions({
     appName,
-    userId
+    userId,
+    limit,
+    offset,
+    page,
+    order
   }) {
     await this.init();
     const em = this.orm.em.fork();
@@ -201,7 +205,49 @@ class DatabaseSessionService extends BaseSessionService {
     if (userId) {
       where.userId = userId;
     }
-    const storageSessions = await em.find(StorageSession, where);
+    const orderBy = order === "asc" ? { updateTime: "ASC", id: "ASC" } : order === "desc" ? { updateTime: "DESC", id: "ASC" } : void 0;
+    let storageSessions;
+    let paginationMeta;
+    if (limit !== void 0) {
+      const totalItems = await em.count(StorageSession, where);
+      const totalPages = limit === 0 ? 0 : Math.ceil(totalItems / limit);
+      let effectiveOffset;
+      let effectivePage;
+      if (page !== void 0) {
+        effectiveOffset = (page - 1) * limit;
+        effectivePage = page;
+      } else {
+        effectiveOffset = offset != null ? offset : 0;
+        effectivePage = limit === 0 ? 1 : Math.floor(effectiveOffset / limit) + 1;
+      }
+      storageSessions = await em.find(StorageSession, where, {
+        orderBy,
+        limit,
+        offset: effectiveOffset
+      });
+      paginationMeta = { page: effectivePage, limit, totalItems, totalPages };
+    } else if (offset) {
+      const totalItems = await em.count(StorageSession, where);
+      storageSessions = await em.find(StorageSession, where, {
+        orderBy,
+        offset
+      });
+      paginationMeta = {
+        page: 1,
+        limit: totalItems,
+        totalItems,
+        totalPages: totalItems === 0 ? 0 : 1
+      };
+    } else {
+      storageSessions = await em.find(StorageSession, where, { orderBy });
+      const totalItems = storageSessions.length;
+      paginationMeta = {
+        page: 1,
+        limit: totalItems,
+        totalItems,
+        totalPages: totalItems === 0 ? 0 : 1
+      };
+    }
     const appStateModel = await em.findOne(StorageAppState, { appName });
     const appState = (appStateModel == null ? void 0 : appStateModel.state) || {};
     const userStateMap = {};
@@ -226,7 +272,7 @@ class DatabaseSessionService extends BaseSessionService {
         lastUpdateTime: ss.updateTime.getTime()
       });
     });
-    return { sessions };
+    return { sessions, ...paginationMeta };
   }
   async deleteSession({
     appName,