@softactivate/adk 1.1.0 → 1.2.0

package/dist/esm/integrations/agent_registry/agent_registry_mcp_toolset.js

@@ -0,0 +1,77 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseToolset } from "../../tools/base_toolset.js";
+import {
+  MCPSessionManager
+} from "../../tools/mcp/mcp_session_manager.js";
+import { MCPTool } from "../../tools/mcp/mcp_tool.js";
+import { GCP_MCP_SERVER_DESTINATION_ID } from "./types.js";
+class AgentRegistrySingleMCPToolset extends BaseToolset {
+  constructor(options) {
+    super(options.toolFilter || [], options.prefix);
+    this.destinationResourceId = options.destinationResourceId;
+    this.connectionParams = options.connectionParams;
+    this.headerProvider = options.headerProvider;
+    this.authScheme = options.authScheme;
+    this.authCredential = options.authCredential;
+  }
+  /**
+   * Connects to the underlying MCP server, retrieves tool definitions, prefixes tool names,
+   * and injects destination telemetry metadata.
+   */
+  async getTools(context) {
+    var _a, _b, _c;
+    const headers = {};
+    if (this.headerProvider) {
+      const providerHeaders = await this.headerProvider(context);
+      Object.assign(headers, providerHeaders);
+    }
+    const connectionParamsCopy = {
+      ...this.connectionParams,
+      transportOptions: {
+        ...this.connectionParams.transportOptions,
+        requestInit: {
+          ...(_a = this.connectionParams.transportOptions) == null ? void 0 : _a.requestInit,
+          headers: {
+            ...(_c = (_b = this.connectionParams.transportOptions) == null ? void 0 : _b.requestInit) == null ? void 0 : _c.headers,
+            ...headers
+          }
+        }
+      }
+    };
+    const sessionManager = new MCPSessionManager(connectionParamsCopy);
+    const session = await sessionManager.createSession();
+    const listResult = await session.listTools();
+    const tools = listResult.tools.map((tool) => {
+      const prefixedName = this.prefix ? `${this.prefix}_${tool.name}` : tool.name;
+      const mcpTool = new MCPTool(
+        { ...tool, name: prefixedName },
+        sessionManager,
+        tool.name
+      );
+      const toolWithMetadata = mcpTool;
+      if (this.destinationResourceId) {
+        if (!toolWithMetadata.customMetadata) {
+          toolWithMetadata.customMetadata = {};
+        }
+        toolWithMetadata.customMetadata[GCP_MCP_SERVER_DESTINATION_ID] = this.destinationResourceId;
+      }
+      return mcpTool;
+    });
+    const filter = this.toolFilter;
+    if (!filter || Array.isArray(filter) && filter.length === 0) {
+      return tools;
+    }
+    return tools.filter((t) => this.isToolSelected(t, context));
+  }
+  async close() {
+  }
+}
+export {
+  AgentRegistrySingleMCPToolset
+};

package/dist/esm/integrations/agent_registry/helpers.js

@@ -0,0 +1,28 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function isGoogleApi(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === "googleapis.com" || parsed.hostname.endsWith(".googleapis.com");
+  } catch {
+    return false;
+  }
+}
+function cleanName(name) {
+  let clean = name.replace(/[^a-zA-Z0-9_]/g, "_");
+  clean = clean.replace(/_+/g, "_");
+  clean = clean.replace(/^_+|_+$/g, "");
+  if (clean && !/^[a-zA-Z_]/.test(clean)) {
+    clean = "_" + clean;
+  }
+  return clean;
+}
+export {
+  cleanName,
+  isGoogleApi
+};

package/dist/esm/integrations/agent_registry/types.js

@@ -0,0 +1,20 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const AGENT_REGISTRY_BASE_URL = "https://agentregistry.googleapis.com/v1alpha";
+const GCP_MCP_SERVER_DESTINATION_ID = "gcp.mcp.server.destination.id";
+var ProtocolType = /* @__PURE__ */ ((ProtocolType2) => {
+  ProtocolType2["TYPE_UNSPECIFIED"] = "TYPE_UNSPECIFIED";
+  ProtocolType2["A2A_AGENT"] = "A2A_AGENT";
+  ProtocolType2["CUSTOM"] = "CUSTOM";
+  return ProtocolType2;
+})(ProtocolType || {});
+export {
+  AGENT_REGISTRY_BASE_URL,
+  GCP_MCP_SERVER_DESTINATION_ID,
+  ProtocolType
+};

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