@google/adk 1.6.0 → 2.1.0

package/dist/cjs/runner/runner.js

@@ -9,6 +9,7 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -33,11 +34,14 @@ __export(runner_exports, {
 module.exports = __toCommonJS(runner_exports);
 var import_genai = require("@google/genai");
 var import_api = require("@opentelemetry/api");
+var import_base_agent = require("../agents/base_agent.js");
+var import_framework_function_calls = require("../agents/framework_function_calls.js");
 var import_functions = require("../agents/functions.js");
 var import_invocation_context = require("../agents/invocation_context.js");
 var import_llm_agent = require("../agents/llm_agent.js");
 var import_run_config = require("../agents/run_config.js");
 var import_scoped_artifact_service = require("../artifacts/scoped_artifact_service.js");
+var import_session_artifact_service = require("../artifacts/session_artifact_service.js");
 var import_built_in_code_executor = require("../code_executors/built_in_code_executor.js");
 var import_event = require("../events/event.js");
 var import_event_actions = require("../events/event_actions.js");
@@ -46,18 +50,21 @@ var import_tracing = require("../telemetry/tracing.js");
 var import_base_toolset = require("../tools/base_toolset.js");
 var import_logger = require("../utils/logger.js");
 var import_model_name = require("../utils/model_name.js");
+var import_redact_inline_data = require("../utils/redact_inline_data.js");
+var import_run_node_as_invocation = require("../workflow/run_node_as_invocation.js");
 /**
  * @license
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
 var _a;
-const RUNNER_SIGNATURE_SYMBOL = Symbol.for("google.adk.runner");
+const RUNNER_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for("google.adk.runner");
 function isRunner(obj) {
   return typeof obj === "object" && obj !== null && RUNNER_SIGNATURE_SYMBOL in obj && obj[RUNNER_SIGNATURE_SYMBOL] === true;
 }
+__name(isRunner, "isRunner");
 _a = RUNNER_SIGNATURE_SYMBOL;
-class Runner {
+const _Runner = class _Runner {
   /**
    * Creates a new Runner instance.
    *
@@ -74,7 +81,7 @@ class Runner {
       );
     }
     this.appName = appName;
-    this.agent = agent;
+    this.agent = (0, import_run_node_as_invocation.asRunnableRoot)(agent);
     const appPlugins = (_f = (_e = input.app) == null ? void 0 : _e.plugins) != null ? _f : [];
     const configPlugins = (_g = input.plugins) != null ? _g : [];
     this.pluginManager = new import_plugin_manager.PluginManager([...appPlugins, ...configPlugins]);
@@ -135,6 +142,7 @@ class Runner {
     if (newMessage && !newMessage.role) {
       newMessage.role = "user";
     }
+    rejectReservedFunctionCalls(newMessage);
     const span = import_tracing.tracer.startSpan("invocation");
     const ctx = import_api.trace.setSpan(import_api.context.active(), span);
     try {
@@ -157,7 +165,9 @@ class Runner {
                 `Session lookup failed: appName must be provided in runner constructor (or via app.name)`
               );
             }
-            throw new Error(`Session not found: ${sessionId}`);
+            throw new Error(
+              `Session not found: ${sessionId} (appName=${this.appName}, userId=${userId})`
+            );
           }
           if (runConfig.supportCfc && (0, import_llm_agent.isLlmAgent)(this.agent)) {
             const modelName = this.agent.canonicalModel.model;
@@ -171,7 +181,7 @@ class Runner {
             }
           }
           const invocationContext = new import_invocation_context.InvocationContext({
-            artifactService: this.artifactService ? new import_scoped_artifact_service.ScopedArtifactService(
+            artifactService: this.artifactService ? (0, import_session_artifact_service.isSessionArtifactService)(this.artifactService) ? this.artifactService : new import_scoped_artifact_service.ScopedArtifactService(
               this.artifactService,
               this.appName,
               userId,
@@ -181,10 +191,11 @@ class Runner {
             memoryService: this.memoryService,
             credentialService: this.credentialService,
             invocationId: (0, import_invocation_context.newInvocationContextId)(),
-            agent: this.agent,
+            agent: (0, import_base_agent.isBaseAgent)(this.agent) ? this.agent : void 0,
             session,
             userContent: newMessage,
             runConfig,
+            a2aMetadata: runConfig.a2aMetadata,
             pluginManager: this.pluginManager,
             abortSignal: params.abortSignal
           });
@@ -204,9 +215,8 @@ class Runner {
             }
             if (runConfig.saveInputBlobsAsArtifacts) {
               newMessage = await this.saveArtifacts(
+                invocationContext.artifactService,
                 invocationContext.invocationId,
-                session.userId,
-                session.id,
                 newMessage
               );
               if ((_d = params.abortSignal) == null ? void 0 : _d.aborted) {
@@ -227,10 +237,12 @@ class Runner {
               return;
             }
           }
-          invocationContext.agent = this.determineAgentForResumption(
-            session,
-            this.agent
-          );
+          if ((0, import_base_agent.isBaseAgent)(this.agent)) {
+            invocationContext.agent = this.determineAgentForResumption(
+              session,
+              this.agent
+            );
+          }
           if (newMessage) {
             const beforeRunCallbackResponse = await this.pluginManager.runBeforeRunCallback({
               invocationContext
@@ -253,9 +265,7 @@ class Runner {
               }
               yield earlyExitEvent;
             } else {
-              for await (const event of invocationContext.agent.runAsync(
-                invocationContext
-              )) {
+              for await (const event of this.runRoot(invocationContext)) {
                 if ((_h = params.abortSignal) == null ? void 0 : _h.aborted) {
                   return;
                 }
@@ -292,29 +302,42 @@ class Runner {
       );
     } finally {
       span.end();
-      const toolsets = getAllToolsets(this.agent);
+      const toolsets = (0, import_base_agent.isBaseAgent)(this.agent) ? getAllToolsets(this.agent) : [];
       await Promise.allSettled(toolsets.map((t) => t.close()));
     }
   }
+  /**
+   * Runs whatever this runner was given as its root.
+   *
+   * An agent is run through `runAsync`, as always. A bare node — a `Workflow`
+   * handed to the runner directly — is driven by {@link runNodeAsInvocation}.
+   *
+   * Only the execution differs. Everything around it (the run callbacks, event
+   * persistence, cancellation) is shared, so the node path cannot drift from
+   * the agent path on the things that are not about execution. adk-python has
+   * two separate loops here and a TODO noting its node one lacks tracing and
+   * plugins; there is nothing to lack if there is only one loop.
+   */
+  async *runRoot(invocationContext) {
+    if ((0, import_base_agent.isBaseAgent)(this.agent)) {
+      yield* (0, import_invocation_context.requireAgent)(invocationContext).runAsync(invocationContext);
+      return;
+    }
+    yield* (0, import_run_node_as_invocation.runNodeAsInvocation)(this.agent, invocationContext);
+  }
   /**
    * Saves artifacts from the message parts and replaces the inline data with
    * a file name placeholder and optional file reference.
    *
+   * @param artifactService The session-scoped artifact service to save to.
    * @param invocationId The current invocation ID.
-   * @param userId The user ID of the session.
-   * @param sessionId The session ID of the session.
    * @param message The message containing parts to process.
    */
-  async saveArtifacts(invocationId, userId, sessionId, message) {
+  async saveArtifacts(artifactService, invocationId, message) {
     var _a2;
-    if (!this.artifactService || !((_a2 = message.parts) == null ? void 0 : _a2.length)) {
+    if (!artifactService || !((_a2 = message.parts) == null ? void 0 : _a2.length)) {
       return message;
     }
-    const sessionKey = {
-      appName: this.appName,
-      userId,
-      sessionId
-    };
     const newParts = [];
     let modified = false;
     for (let i = 0; i < message.parts.length; i++) {
@@ -326,20 +349,16 @@ class Runner {
       try {
         const inlineData = part.inlineData;
         const fileName = inlineData.displayName || `artifact_${invocationId}_${i}`;
-        const version = await this.artifactService.saveArtifact({
-          ...sessionKey,
+        const version = await artifactService.saveArtifact({
           filename: fileName,
           artifact: part
         });
         newParts.push((0, import_genai.createPartFromText)(`[Uploaded Artifact: "${fileName}"]`));
         try {
-          const artifactVersion = await this.artifactService.getArtifactVersion(
-            {
-              ...sessionKey,
-              filename: fileName,
-              version
-            }
-          );
+          const artifactVersion = await artifactService.getArtifactVersion({
+            filename: fileName,
+            version
+          });
           if ((artifactVersion == null ? void 0 : artifactVersion.canonicalUri) && /^(gs|https?):/i.test(artifactVersion.canonicalUri)) {
             newParts.push({
               fileData: {
@@ -389,27 +408,180 @@ class Runner {
    * Whether the agent to run can transfer to any other agent in the agent tree.
    *
    * @param agentToRun The agent to check for transferability.
-   * @returns True if the agent can transfer, False otherwise.
+   * @returns True if the agent can transfer, false otherwise.
    */
   isRoutableLlmAgent(agentToRun) {
     return isRoutableLlmAgent(agentToRun);
   }
-  // TODO - b/425992518: Implement runLive and related methods.
+  /**
+   * Runs the agent in the live (bidirectional streaming) mode.
+   *
+   * Model media events that carry raw inline bytes (audio, video, or image)
+   * are yielded but not appended to the session to avoid persisting large
+   * blobs; events with `fileData` references and most other live events
+   * (transcriptions, tool calls, usage) are persisted as in `runAsync`.
+   *
+   * This feature is **experimental** and its API may change.
+   *
+   * @param params.userId The user ID of the session.
+   * @param params.sessionId The session ID of the session.
+   * @param params.liveRequestQueue The queue used to feed the live model.
+   * @param params.runConfig The run config for the agent.
+   * @param params.abortSignal Optional signal to abort the live run.
+   * @param params.liveSessionResumptionHandle Optional session resumption
+   *     handle observed from a prior `runLive` cycle on the same conversation.
+   *     When set, the agent's live flow opens the connection with
+   *     `liveConnectConfig.sessionResumption.handle` so the server restores its
+   *     state instead of relying on client-side history replay.
+   * @yields The events generated by the agent.
+   */
+  async *runLive(params) {
+    var _a2, _b, _c, _d;
+    if (!params.liveRequestQueue) {
+      throw new Error("liveRequestQueue is required for runLive.");
+    }
+    if (!(0, import_base_agent.isBaseAgent)(this.agent)) {
+      throw new Error("runLive is only supported for agents.");
+    }
+    const agent = this.agent;
+    const runConfig = (0, import_run_config.createRunConfig)(params.runConfig);
+    if (!((_a2 = runConfig.responseModalities) == null ? void 0 : _a2.length)) {
+      runConfig.responseModalities = [import_genai.Modality.AUDIO];
+    }
+    if ((_b = agent.subAgents) == null ? void 0 : _b.length) {
+      if (runConfig.responseModalities.includes(import_genai.Modality.AUDIO)) {
+        (_c = runConfig.outputAudioTranscription) != null ? _c : runConfig.outputAudioTranscription = {};
+      }
+      (_d = runConfig.inputAudioTranscription) != null ? _d : runConfig.inputAudioTranscription = {};
+    }
+    const span = import_tracing.tracer.startSpan("invocation");
+    const ctx = import_api.trace.setSpan(import_api.context.active(), span);
+    try {
+      yield* (0, import_tracing.runAsyncGeneratorWithOtelContext)(
+        ctx,
+        this,
+        async function* () {
+          var _a3, _b2, _c2, _d2;
+          const session = await this.sessionService.getOrCreateSession({
+            appName: this.appName,
+            userId: params.userId,
+            sessionId: params.sessionId
+          });
+          if ((_a3 = params.abortSignal) == null ? void 0 : _a3.aborted) {
+            return;
+          }
+          const invocationContext = new import_invocation_context.InvocationContext({
+            artifactService: this.artifactService ? (0, import_session_artifact_service.isSessionArtifactService)(this.artifactService) ? this.artifactService : new import_scoped_artifact_service.ScopedArtifactService(
+              this.artifactService,
+              this.appName,
+              params.userId,
+              params.sessionId
+            ) : void 0,
+            sessionService: this.sessionService,
+            memoryService: this.memoryService,
+            credentialService: this.credentialService,
+            invocationId: (0, import_invocation_context.newInvocationContextId)(),
+            agent,
+            session,
+            runConfig,
+            a2aMetadata: runConfig.a2aMetadata,
+            pluginManager: this.pluginManager,
+            liveRequestQueue: params.liveRequestQueue,
+            abortSignal: params.abortSignal,
+            liveSessionResumptionHandle: params.liveSessionResumptionHandle
+          });
+          invocationContext.agent = this.determineAgentForResumption(
+            session,
+            agent
+          );
+          const beforeRunCallbackResponse = await this.pluginManager.runBeforeRunCallback({
+            invocationContext
+          });
+          if ((_b2 = params.abortSignal) == null ? void 0 : _b2.aborted) {
+            return;
+          }
+          if (beforeRunCallbackResponse) {
+            const earlyExitEvent = (0, import_event.createEvent)({
+              invocationId: invocationContext.invocationId,
+              author: "model",
+              content: beforeRunCallbackResponse
+            });
+            await this.sessionService.appendEvent({
+              session,
+              event: earlyExitEvent
+            });
+            yield earlyExitEvent;
+            return;
+          }
+          for await (const event of (0, import_invocation_context.requireAgent)(invocationContext).runLive(
+            invocationContext
+          )) {
+            if ((_c2 = params.abortSignal) == null ? void 0 : _c2.aborted) {
+              return;
+            }
+            const modifiedEvent = await this.pluginManager.runOnEventCallback({
+              invocationContext,
+              event
+            });
+            if ((_d2 = params.abortSignal) == null ? void 0 : _d2.aborted) {
+              return;
+            }
+            const eventToProcess = modifiedEvent != null ? modifiedEvent : event;
+            if (!eventToProcess.partial && !isLiveModelMediaEventWithInlineData(eventToProcess)) {
+              await this.sessionService.appendEvent({
+                session,
+                event: eventToProcess
+              });
+            }
+            yield eventToProcess;
+          }
+          await this.pluginManager.runAfterRunCallback({ invocationContext });
+        }
+      );
+    } finally {
+      span.end();
+    }
+  }
+};
+__name(_Runner, "Runner");
+let Runner = _Runner;
+function isLiveModelMediaEventWithInlineData(event) {
+  var _a2;
+  const parts = (_a2 = event.content) == null ? void 0 : _a2.parts;
+  if (!(parts == null ? void 0 : parts.length)) {
+    return false;
+  }
+  return parts.some((part) => {
+    var _a3, _b;
+    const mimeType = (_b = (_a3 = part.inlineData) == null ? void 0 : _a3.mimeType) == null ? void 0 : _b.toLowerCase();
+    return mimeType !== void 0 && (mimeType.startsWith("audio/") || mimeType.startsWith("video/") || mimeType.startsWith("image/"));
+  });
 }
+__name(isLiveModelMediaEventWithInlineData, "isLiveModelMediaEventWithInlineData");
 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 conflictingAuthors = (0, import_functions.getConflictingFunctionResponseAuthors)(
+      session.events
+    );
+    if (conflictingAuthors) {
+      throw new Error(
+        `Function responses in the last event resolve to function calls from more than one agent (at least "${conflictingAuthors[0]}" and "${conflictingAuthors[1]}"); cannot determine a single agent to resume.`
+      );
+    }
     const resumedAgent = rootAgent.findAgent(event.author);
     if (resumedAgent) {
       return resumedAgent;
     }
-    import_logger.logger.warn(
-      `Function response from an unknown agent: ${event.author}, event id: ${event.id}`
-    );
+    if (!isWorkflowNodeEvent(event)) {
+      import_logger.logger.warn(
+        `Function response from an unknown agent: ${event.author}, event id: ${event.id}`
+      );
+    }
   }
   for (let i = session.events.length - 1; i >= 0; i--) {
-    import_logger.logger.debug("event:", JSON.stringify(session.events[i]));
+    import_logger.logger.debug("event:", (0, import_redact_inline_data.stringifyWithRedactedInlineData)(session.events[i]));
     const event2 = session.events[i];
     if (event2.author === "user" || !event2.author) {
       continue;
@@ -419,9 +591,11 @@ function determineAgentForResumption(session, rootAgent, resumabilityConfig) {
     }
     const agent = rootAgent.findSubAgent(event2.author);
     if (!agent) {
-      import_logger.logger.warn(
-        `Event from an unknown agent: ${event2.author}, event id: ${event2.id}`
-      );
+      if (!isWorkflowNodeEvent(event2)) {
+        import_logger.logger.warn(
+          `Event from an unknown agent: ${event2.author}, event id: ${event2.id}`
+        );
+      }
       continue;
     }
     if (isRoutableLlmAgent(agent)) {
@@ -430,6 +604,12 @@ function determineAgentForResumption(session, rootAgent, resumabilityConfig) {
   }
   return rootAgent;
 }
+__name(determineAgentForResumption, "determineAgentForResumption");
+function isWorkflowNodeEvent(event) {
+  var _a2;
+  return Boolean((_a2 = event.nodeInfo) == null ? void 0 : _a2.path);
+}
+__name(isWorkflowNodeEvent, "isWorkflowNodeEvent");
 function isRoutableLlmAgent(agentToRun) {
   let agent = agentToRun;
   while (agent) {
@@ -443,10 +623,12 @@ function isRoutableLlmAgent(agentToRun) {
   }
   return true;
 }
+__name(isRoutableLlmAgent, "isRoutableLlmAgent");
 function findEventByLastFunctionResponseId(events) {
   var _a2;
   return (_a2 = (0, import_functions.findMatchingFunctionCall)(events)) != null ? _a2 : null;
 }
+__name(findEventByLastFunctionResponseId, "findEventByLastFunctionResponseId");
 function getAllToolsets(agent) {
   const toolsets = [];
   const visited = /* @__PURE__ */ new Set();
@@ -464,9 +646,20 @@ function getAllToolsets(agent) {
       traverse(sub);
     }
   }
+  __name(traverse, "traverse");
   traverse(agent);
   return toolsets;
 }
+__name(getAllToolsets, "getAllToolsets");
+function rejectReservedFunctionCalls(newMessage) {
+  const reserved = (0, import_framework_function_calls.reservedFunctionCallName)(newMessage);
+  if (reserved) {
+    throw new Error(
+      `A client message may not contain a '${reserved}' function call: it is raised by the framework, and can only be answered with a function response.`
+    );
+  }
+}
+__name(rejectReservedFunctionCalls, "rejectReservedFunctionCalls");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Runner,

package/dist/cjs/sessions/base_session_service.js

@@ -9,6 +9,7 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -32,12 +33,13 @@ __export(base_session_service_exports, {
 module.exports = __toCommonJS(base_session_service_exports);
 var import_lodash_es = require("lodash-es");
 var import_state = require("./state.js");
+var import_state_write_order = require("./state_write_order.js");
 /**
  * @license
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-class BaseSessionService {
+const _BaseSessionService = class _BaseSessionService {
   /**
    * Gets a session or creates one if it doesn't exist.
    *
@@ -91,6 +93,9 @@ class BaseSessionService {
       if (key.startsWith(import_state.State.TEMP_PREFIX)) {
         continue;
       }
+      if (!(0, import_state_write_order.shouldApplyDeltaWrite)(session.state, event.actions.stateDelta, key)) {
+        continue;
+      }
       Object.defineProperty(session.state, key, {
         value,
         writable: true,
@@ -99,7 +104,9 @@ class BaseSessionService {
       });
     }
   }
-}
+};
+__name(_BaseSessionService, "BaseSessionService");
+let BaseSessionService = _BaseSessionService;
 function trimTempDeltaState(event) {
   if (!event.actions || !event.actions.stateDelta) {
     return event;
@@ -111,9 +118,11 @@ function trimTempDeltaState(event) {
       filteredStateDelta[key] = value;
     }
   }
+  (0, import_state_write_order.carryDeltaStamps)(stateDelta, filteredStateDelta);
   event.actions.stateDelta = filteredStateDelta;
   return event;
 }
+__name(trimTempDeltaState, "trimTempDeltaState");
 function trimTempState(state) {
   const filteredState = /* @__PURE__ */ Object.create(null);
   for (const [key, value] of Object.entries(state)) {
@@ -123,6 +132,7 @@ function trimTempState(state) {
   }
   return filteredState;
 }
+__name(trimTempState, "trimTempState");
 function mergeStates(appState = {}, userState = {}, sessionState = {}) {
   const merged = (0, import_lodash_es.cloneDeep)(sessionState);
   for (const [k, v] of Object.entries(appState)) {
@@ -133,6 +143,7 @@ function mergeStates(appState = {}, userState = {}, sessionState = {}) {
   }
   return merged;
 }
+__name(mergeStates, "mergeStates");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseSessionService,