@google/adk 1.3.0 → 1.5.0

package/dist/esm/plugins/global_instruction_plugin.js

@@ -0,0 +1,69 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { injectSessionState } from "../agents/instructions.js";
+import { ReadonlyContext } from "../agents/readonly_context.js";
+import { BasePlugin } from "./base_plugin.js";
+class GlobalInstructionPlugin extends BasePlugin {
+  /**
+   * Initializes the GlobalInstructionPlugin.
+   *
+   * @param globalInstruction The instruction to apply globally. Can be a string
+   *     or an InstructionProvider function that takes ReadonlyContext and
+   *     returns a string (sync or async).
+   * @param name The name of the plugin (defaults to 'global_instruction').
+   */
+  constructor(globalInstruction, name = "global_instruction") {
+    super(name);
+    this.globalInstruction = globalInstruction;
+  }
+  async beforeModelCallback(params) {
+    if (!this.globalInstruction) {
+      return;
+    }
+    const readonlyContext = new ReadonlyContext(
+      params.callbackContext.invocationContext
+    );
+    const finalGlobalInstruction = await this.resolveGlobalInstruction(readonlyContext);
+    if (!finalGlobalInstruction) {
+      return;
+    }
+    if (!params.llmRequest.config) {
+      params.llmRequest.config = {};
+    }
+    const existingInstruction = params.llmRequest.config.systemInstruction;
+    if (!existingInstruction || Array.isArray(existingInstruction) && existingInstruction.length === 0) {
+      params.llmRequest.config.systemInstruction = finalGlobalInstruction;
+      return;
+    }
+    if (typeof existingInstruction === "string") {
+      params.llmRequest.config.systemInstruction = `${finalGlobalInstruction}
+
+${existingInstruction}`;
+    } else if (Array.isArray(existingInstruction)) {
+      params.llmRequest.config.systemInstruction = [
+        finalGlobalInstruction,
+        ...existingInstruction
+      ];
+    } else {
+      params.llmRequest.config.systemInstruction = [
+        finalGlobalInstruction,
+        existingInstruction
+      ];
+    }
+    return;
+  }
+  async resolveGlobalInstruction(readonlyContext) {
+    if (typeof this.globalInstruction === "string") {
+      return await injectSessionState(this.globalInstruction, readonlyContext);
+    }
+    return await this.globalInstruction(readonlyContext);
+  }
+}
+export {
+  GlobalInstructionPlugin
+};

package/dist/esm/runner/in_memory_runner.js

@@ -14,19 +14,30 @@ class InMemoryRunner extends Runner {
    * Creates a new InMemoryRunner instance.
    *
    * @param params The configuration for the runner.
+   * @param params.app An optional application instance to run.
    * @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.
+   * @param params.resumabilityConfig An optional resumability configuration.
    */
   constructor(params) {
-    const { agent, appName = "InMemoryRunner", plugins = [] } = params;
+    var _a;
+    const {
+      agent,
+      appName = "InMemoryRunner",
+      plugins = [],
+      app,
+      resumabilityConfig
+    } = params;
     super({
+      app,
       appName,
       agent,
       plugins,
       artifactService: new InMemoryArtifactService(),
       sessionService: new InMemorySessionService(),
-      memoryService: new InMemoryMemoryService()
+      memoryService: new InMemoryMemoryService(),
+      resumabilityConfig: (_a = app == null ? void 0 : app.resumabilityConfig) != null ? _a : resumabilityConfig
     });
   }
 }

package/dist/esm/runner/runner.js

@@ -8,17 +8,19 @@ const require = topLevelCreateRequire(import.meta.url);
 var _a;
 import { createPartFromText } from "@google/genai";
 import { context, trace } from "@opentelemetry/api";
+import { findMatchingFunctionCall } from "../agents/functions.js";
 import {
   InvocationContext,
   newInvocationContextId
 } from "../agents/invocation_context.js";
 import { isLlmAgent } from "../agents/llm_agent.js";
 import { createRunConfig } from "../agents/run_config.js";
+import { ScopedArtifactService } from "../artifacts/scoped_artifact_service.js";
 import {
   BuiltInCodeExecutor,
   isBuiltInCodeExecutor
 } from "../code_executors/built_in_code_executor.js";
-import { createEvent, getFunctionCalls } from "../events/event.js";
+import { createEvent } from "../events/event.js";
 import { createEventActions } from "../events/event_actions.js";
 import { PluginManager } from "../plugins/plugin_manager.js";
 import {
@@ -41,14 +43,24 @@ class Runner {
    */
   constructor(input) {
     this[_a] = true;
-    var _a2;
-    this.appName = input.appName;
-    this.agent = input.agent;
-    this.pluginManager = new PluginManager((_a2 = input.plugins) != null ? _a2 : []);
+    var _a2, _b, _c, _d, _e, _f, _g, _h, _i;
+    const appName = (_b = (_a2 = input.app) == null ? void 0 : _a2.name) != null ? _b : input.appName;
+    const agent = (_d = (_c = input.app) == null ? void 0 : _c.rootAgent) != null ? _d : input.agent;
+    if (!agent) {
+      throw new Error(
+        "agent must be provided in runner constructor (or via app.rootAgent)"
+      );
+    }
+    this.appName = appName;
+    this.agent = agent;
+    const appPlugins = (_f = (_e = input.app) == null ? void 0 : _e.plugins) != null ? _f : [];
+    const configPlugins = (_g = input.plugins) != null ? _g : [];
+    this.pluginManager = new PluginManager([...appPlugins, ...configPlugins]);
     this.artifactService = input.artifactService;
     this.sessionService = input.sessionService;
     this.memoryService = input.memoryService;
     this.credentialService = input.credentialService;
+    this.resumabilityConfig = (_i = (_h = input.app) == null ? void 0 : _h.resumabilityConfig) != null ? _i : input.resumabilityConfig;
   }
   /**
    * Runs the agent with a new, ephemeral session.
@@ -98,6 +110,9 @@ class Runner {
     const { userId, sessionId, stateDelta } = params;
     const runConfig = createRunConfig(params.runConfig);
     let newMessage = params.newMessage;
+    if (newMessage && !newMessage.role) {
+      newMessage.role = "user";
+    }
     const span = tracer.startSpan("invocation");
     const ctx = trace.setSpan(context.active(), span);
     try {
@@ -117,7 +132,7 @@ class Runner {
           if (!session) {
             if (!this.appName) {
               throw new Error(
-                `Session lookup failed: appName must be provided in runner constructor`
+                `Session lookup failed: appName must be provided in runner constructor (or via app.name)`
               );
             }
             throw new Error(`Session not found: ${sessionId}`);
@@ -134,7 +149,12 @@ class Runner {
             }
           }
           const invocationContext = new InvocationContext({
-            artifactService: this.artifactService,
+            artifactService: this.artifactService ? new ScopedArtifactService(
+              this.artifactService,
+              this.appName,
+              userId,
+              sessionId
+            ) : void 0,
             sessionService: this.sessionService,
             memoryService: this.memoryService,
             credentialService: this.credentialService,
@@ -161,7 +181,7 @@ class Runner {
               throw new Error("No parts in the newMessage.");
             }
             if (runConfig.saveInputBlobsAsArtifacts) {
-              await this.saveArtifacts(
+              newMessage = await this.saveArtifacts(
                 invocationContext.invocationId,
                 session.userId,
                 session.id,
@@ -249,7 +269,7 @@ class Runner {
   }
   /**
    * Saves artifacts from the message parts and replaces the inline data with
-   * a file name placeholder.
+   * a file name placeholder and optional file reference.
    *
    * @param invocationId The current invocation ID.
    * @param userId The user ID of the session.
@@ -259,110 +279,144 @@ class Runner {
   async saveArtifacts(invocationId, userId, sessionId, message) {
     var _a2;
     if (!this.artifactService || !((_a2 = message.parts) == null ? void 0 : _a2.length)) {
-      return;
+      return message;
     }
+    const sessionKey = {
+      appName: this.appName,
+      userId,
+      sessionId
+    };
+    const newParts = [];
+    let modified = false;
     for (let i = 0; i < message.parts.length; i++) {
       const part = message.parts[i];
       if (!part.inlineData) {
+        newParts.push(part);
         continue;
       }
-      const fileName = `artifact_${invocationId}_${i}`;
-      await this.artifactService.saveArtifact({
-        appName: this.appName,
-        userId,
-        sessionId,
-        filename: fileName,
-        artifact: part
-      });
-      message.parts[i] = createPartFromText(
-        `Uploaded file: ${fileName}. It is saved into artifacts`
-      );
+      try {
+        const inlineData = part.inlineData;
+        const fileName = inlineData.displayName || `artifact_${invocationId}_${i}`;
+        const version = await this.artifactService.saveArtifact({
+          ...sessionKey,
+          filename: fileName,
+          artifact: part
+        });
+        newParts.push(createPartFromText(`[Uploaded Artifact: "${fileName}"]`));
+        try {
+          const artifactVersion = await this.artifactService.getArtifactVersion(
+            {
+              ...sessionKey,
+              filename: fileName,
+              version
+            }
+          );
+          if ((artifactVersion == null ? void 0 : artifactVersion.canonicalUri) && /^(gs|https?):/i.test(artifactVersion.canonicalUri)) {
+            newParts.push({
+              fileData: {
+                fileUri: artifactVersion.canonicalUri,
+                mimeType: artifactVersion.mimeType || inlineData.mimeType || "",
+                displayName: fileName
+              }
+            });
+          }
+        } catch (error) {
+          logger.warn(
+            `Failed to resolve artifact version for ${fileName}:`,
+            error
+          );
+        }
+        modified = true;
+        logger.info(`Successfully saved artifact: ${fileName}`);
+      } catch (error) {
+        logger.error(`Failed to save artifact for part ${i}:`, error);
+        newParts.push(part);
+      }
+    }
+    if (!modified) {
+      return message;
     }
+    return {
+      ...message,
+      parts: newParts
+    };
   }
   /**
    * Determines the next agent to run to continue the session. This is primarily
    * used for session resumption.
    */
-  // TODO - b/425992518: This is where LRO integration should happen.
-  // Needs clean up before we can generalize it.
+  /**
+   * Determines the next agent to run to continue the session. This is primarily
+   * used for session resumption across tool and LRO boundaries.
+   */
   determineAgentForResumption(session, rootAgent) {
-    const event = findEventByLastFunctionResponseId(session.events);
-    if (event && event.author) {
-      return rootAgent.findAgent(event.author) || rootAgent;
-    }
-    for (let i = session.events.length - 1; i >= 0; i--) {
-      logger.info("event:", JSON.stringify(session.events[i]));
-      const event2 = session.events[i];
-      if (event2.author === "user" || !event2.author) {
-        continue;
-      }
-      if (event2.author === rootAgent.name) {
-        return rootAgent;
-      }
-      const agent = rootAgent.findSubAgent(event2.author);
-      if (!agent) {
-        logger.warn(
-          `Event from an unknown agent: ${event2.author}, event id: ${event2.id}`
-        );
-        continue;
-      }
-      if (this.isRoutableLlmAgent(agent)) {
-        return agent;
-      }
-    }
-    return rootAgent;
+    return determineAgentForResumption(
+      session,
+      rootAgent,
+      this.resumabilityConfig
+    );
   }
   /**
    * Whether the agent to run can transfer to any other agent in the agent tree.
    *
-   * An agent is transferable if:
-   *  - It is an instance of `LlmAgent`.
-   *  - All its ancestors are also transferable (i.e., they have
-   *    `disallowTransferToParent` set to false).
-   *
    * @param agentToRun The agent to check for transferability.
    * @returns True if the agent can transfer, False otherwise.
    */
   isRoutableLlmAgent(agentToRun) {
-    let agent = agentToRun;
-    while (agent) {
-      if (!isLlmAgent(agent)) {
-        return false;
-      }
-      if (agent.disallowTransferToParent) {
-        return false;
-      }
-      agent = agent.parentAgent;
-    }
-    return true;
+    return isRoutableLlmAgent(agentToRun);
   }
   // TODO - b/425992518: Implement runLive and related methods.
 }
-function findEventByLastFunctionResponseId(events) {
-  var _a2, _b, _c, _d;
-  if (!events.length) {
-    return null;
-  }
-  const lastEvent = events[events.length - 1];
-  const functionCallId = (_d = (_c = (_b = (_a2 = lastEvent.content) == null ? void 0 : _a2.parts) == null ? void 0 : _b.find(
-    (part) => part.functionResponse
-  )) == null ? void 0 : _c.functionResponse) == null ? void 0 : _d.id;
-  if (!functionCallId) {
-    return null;
+function determineAgentForResumption(session, rootAgent, resumabilityConfig) {
+  const event = findEventByLastFunctionResponseId(session.events);
+  const isResumable = Boolean(resumabilityConfig == null ? void 0 : resumabilityConfig.isResumable);
+  if (event && event.author && isResumable) {
+    const resumedAgent = rootAgent.findAgent(event.author);
+    if (resumedAgent) {
+      return resumedAgent;
+    }
+    logger.warn(
+      `Function response from an unknown agent: ${event.author}, event id: ${event.id}`
+    );
   }
-  for (let i = events.length - 2; i >= 0; i--) {
-    const event = events[i];
-    const functionCalls = getFunctionCalls(event);
-    if (!functionCalls) {
+  for (let i = session.events.length - 1; i >= 0; i--) {
+    logger.debug("event:", JSON.stringify(session.events[i]));
+    const event2 = session.events[i];
+    if (event2.author === "user" || !event2.author) {
       continue;
     }
-    for (const functionCall of functionCalls) {
-      if (functionCall.id === functionCallId) {
-        return event;
-      }
+    if (event2.author === rootAgent.name) {
+      return rootAgent;
+    }
+    const agent = rootAgent.findSubAgent(event2.author);
+    if (!agent) {
+      logger.warn(
+        `Event from an unknown agent: ${event2.author}, event id: ${event2.id}`
+      );
+      continue;
+    }
+    if (isRoutableLlmAgent(agent)) {
+      return agent;
     }
   }
-  return null;
+  return rootAgent;
+}
+function isRoutableLlmAgent(agentToRun) {
+  let agent = agentToRun;
+  while (agent) {
+    if (!isLlmAgent(agent)) {
+      return false;
+    }
+    if (agent.disallowTransferToParent) {
+      return false;
+    }
+    agent = agent.parentAgent;
+  }
+  return true;
+}
+function findEventByLastFunctionResponseId(events) {
+  var _a2;
+  return (_a2 = findMatchingFunctionCall(events)) != null ? _a2 : null;
 }
 function getAllToolsets(agent) {
   const toolsets = [];
@@ -386,5 +440,8 @@ function getAllToolsets(agent) {
 }
 export {
   Runner,
+  determineAgentForResumption,
+  findEventByLastFunctionResponseId,
+  isRoutableLlmAgent,
   isRunner
 };

package/dist/esm/sessions/base_session_service.js

@@ -40,7 +40,12 @@ class BaseSessionService {
     }
     event = trimTempDeltaState(event);
     this.updateSessionState({ session, event });
-    session.events.push(event);
+    const index = session.events.findIndex((e) => e.id === event.id);
+    if (index >= 0) {
+      session.events[index] = event;
+    } else {
+      session.events.push(event);
+    }
     return event;
   }
   /**

package/dist/esm/sessions/database_session_service.js

@@ -371,16 +371,28 @@ class DatabaseSessionService extends BaseSessionService {
           storageSession.state = { ...storageSession.state, ...sessionDelta };
         }
       }
-      const newStorageEvent = txEm.create(StorageEvent, {
+      const existingStorageEvent = await txEm.findOne(StorageEvent, {
         id: trimmedEvent.id,
         appName: session.appName,
         userId: session.userId,
-        sessionId: session.id,
-        invocationId: trimmedEvent.invocationId,
-        timestamp: new Date(trimmedEvent.timestamp),
-        eventData: trimmedEvent
+        sessionId: session.id
       });
-      txEm.persist(newStorageEvent);
+      if (existingStorageEvent) {
+        existingStorageEvent.eventData = trimmedEvent;
+        existingStorageEvent.timestamp = new Date(trimmedEvent.timestamp);
+        txEm.persist(existingStorageEvent);
+      } else {
+        const newStorageEvent = txEm.create(StorageEvent, {
+          id: trimmedEvent.id,
+          appName: session.appName,
+          userId: session.userId,
+          sessionId: session.id,
+          invocationId: trimmedEvent.invocationId,
+          timestamp: new Date(trimmedEvent.timestamp),
+          eventData: trimmedEvent
+        });
+        txEm.persist(newStorageEvent);
+      }
       await txEm.commit();
       storageSession.updateTime = new Date(event.timestamp);
       const newMergedState = mergeStates(
@@ -389,7 +401,12 @@ class DatabaseSessionService extends BaseSessionService {
         storageSession.state
       );
       session.state = newMergedState;
-      session.events.push(event);
+      const index = session.events.findIndex((e) => e.id === event.id);
+      if (index >= 0) {
+        session.events[index] = event;
+      } else {
+        session.events.push(event);
+      }
       session.lastUpdateTime = storageSession.updateTime.getTime();
     });
     return event;

package/dist/esm/sessions/vertex_ai_session_service.js

@@ -32,6 +32,10 @@ const HTTP_NOT_FOUND = 404;
 function isVertexAiConnectionString(uri) {
   return (uri == null ? void 0 : uri.startsWith("vertexai://")) || false;
 }
+function quoteFilterLiteral(value) {
+  const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return `"${escaped}"`;
+}
 let VertexAiSessionService = class extends BaseSessionService {
   constructor(options) {
     super();
@@ -199,7 +203,7 @@ let VertexAiSessionService = class extends BaseSessionService {
       const response = await this.sessions.listInternal({
         name: `reasoningEngines/${reasoningEngineId}`,
         config: {
-          ...userId ? { filter: `user_id="${userId}"` } : {},
+          ...userId ? { filter: `user_id=${quoteFilterLiteral(userId)}` } : {},
           ...pageToken ? { pageToken } : {}
         }
       });
@@ -260,10 +264,19 @@ let VertexAiSessionService = class extends BaseSessionService {
   }
   async deleteSession({
     appName,
-    userId: _userId,
+    userId,
     sessionId
   }) {
     const reasoningEngineId = this.getReasoningEngineId(appName);
+    const session = await this.getSession({
+      appName,
+      userId,
+      sessionId,
+      config: { numRecentEvents: 0 }
+    });
+    if (!session) {
+      return;
+    }
     await this.sessions.delete({
       name: `reasoningEngines/${reasoningEngineId}/sessions/${sessionId}`
     });
@@ -401,5 +414,6 @@ function _fromApiEvent(apiEventObj) {
 }
 export {
   VertexAiSessionService,
-  isVertexAiConnectionString
+  isVertexAiConnectionString,
+  quoteFilterLiteral
 };

package/dist/esm/skills/loader.js

@@ -84,12 +84,12 @@ function parseSkillMdContent(content) {
   if (!content.startsWith("---")) {
     throw new Error("SKILL.md must start with YAML frontmatter (---)");
   }
-  const parts = content.split("---", 3);
+  const parts = content.split("---");
   if (parts.length < 3) {
     throw new Error("SKILL.md frontmatter not properly closed with ---");
   }
   const frontmatterStr = parts[1];
-  const body = parts[2].trim();
+  const body = parts.filter((_, i) => i >= 2).join("---").trim();
   try {
     const parsed = yaml.load(frontmatterStr);
     if (typeof parsed !== "object" || parsed === null) {

package/dist/esm/tools/base_toolset.js

@@ -25,7 +25,7 @@ class BaseToolset {
    * @return Whether the tool should be exposed to LLM.
    */
   isToolSelected(tool, context) {
-    if (!this.toolFilter) {
+    if (!this.toolFilter || Array.isArray(this.toolFilter) && this.toolFilter.length === 0) {
       return true;
     }
     if (typeof this.toolFilter === "function") {

package/dist/esm/tools/consolidate_context_tool.js

@@ -0,0 +1,51 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Type } from "@google/genai";
+import { BaseTool } from "./base_tool.js";
+class ConsolidateContextTool extends BaseTool {
+  constructor() {
+    super({
+      name: "consolidate_context",
+      description: "Requests context consolidation (compaction) to manage history size. Use this when a subtask is complete and you want to summarize progress and clear detailed history."
+    });
+  }
+  _getDeclaration() {
+    return {
+      name: this.name,
+      description: this.description,
+      parameters: {
+        type: Type.OBJECT,
+        properties: {
+          detail: {
+            type: Type.STRING,
+            description: "Optional description of what has been accomplished so far. This detail will be used to guide the summarization of the history."
+          }
+        }
+      }
+    };
+  }
+  async runAsync({
+    args,
+    toolContext
+  }) {
+    toolContext.state.set("temp:consolidate_context", true);
+    if (args["detail"] !== void 0) {
+      toolContext.state.set(
+        "temp:consolidate_context_detail",
+        args["detail"]
+      );
+    }
+    return {
+      status: "success",
+      message: "Context consolidation requested."
+    };
+  }
+}
+export {
+  ConsolidateContextTool
+};

package/dist/esm/tools/enterprise_web_search_tool.js

@@ -0,0 +1,55 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  isGemini1Model,
+  isGeminiModel,
+  isGeminiModelIdCheckDisabled
+} from "../utils/model_name.js";
+import { BaseTool } from "./base_tool.js";
+function applyEnterpriseWebSearch(llmRequest) {
+  if (!llmRequest.model) {
+    return;
+  }
+  const modelCheckDisabled = isGeminiModelIdCheckDisabled();
+  llmRequest.config = llmRequest.config || {};
+  llmRequest.config.tools = llmRequest.config.tools || [];
+  if (isGeminiModel(llmRequest.model) || modelCheckDisabled) {
+    if (isGemini1Model(llmRequest.model) && llmRequest.config.tools.length > 0) {
+      throw new Error(
+        "Enterprise Web Search tool cannot be used with other tools in Gemini 1.x."
+      );
+    }
+    llmRequest.config.tools.push({ enterpriseWebSearch: {} });
+    return;
+  }
+  throw new Error(
+    `Enterprise Web Search tool is not supported for model ${llmRequest.model}`
+  );
+}
+class EnterpriseWebSearchTool extends BaseTool {
+  constructor() {
+    super({
+      name: "enterprise_web_search",
+      description: "Enterprise Web Search Tool"
+    });
+  }
+  runAsync() {
+    return Promise.resolve();
+  }
+  async processLlmRequest({
+    llmRequest
+  }) {
+    applyEnterpriseWebSearch(llmRequest);
+  }
+}
+const ENTERPRISE_WEB_SEARCH = new EnterpriseWebSearchTool();
+export {
+  ENTERPRISE_WEB_SEARCH,
+  EnterpriseWebSearchTool,
+  applyEnterpriseWebSearch
+};