@google/adk 2.3.0 → 2.5.0

package/dist/esm/index.js

@@ -74,14 +74,17 @@ import {
 import {
   IntegrationClient
 } from "./tools/application_integration_tool/clients/integration_client.js";
+import {
+  IntegrationConnectorTool
+} from "./tools/application_integration_tool/integration_connector_tool.js";
 import { LOAD_WEB_PAGE, loadWebPage } from "./tools/load_web_page.js";
 import {
   credentialToParam,
-  dictToAuthScheme,
   INTERNAL_AUTH_PREFIX,
-  openidDictToSchemeCredential,
+  openidRecordToSchemeCredential,
   openidUrlToSchemeCredential,
-  serviceAccountDictToSchemeCredential,
+  recordToAuthScheme,
+  serviceAccountRecordToSchemeCredential,
   serviceAccountSchemeCredential,
   tokenToSchemeCredential
 } from "./tools/openapi_tool/auth/auth_helpers.js";
@@ -123,16 +126,25 @@ import {
 import { RunSkillScriptTool } from "./tools/skill/run_skill_script_tool.js";
 import { SkillToolset } from "./tools/skill/skill_toolset.js";
 export * from "./integrations/agent_registry/agent_registry.js";
-export * from "./telemetry/google_cloud.js";
-export * from "./telemetry/setup.js";
+import { runWithAgentEngineContext } from "./telemetry/export/agent_engine.js";
+import {
+  agentRuntimeRequestHooks
+} from "./telemetry/export/agent_runtime.js";
+export * from "./telemetry/export/google_cloud.js";
+export * from "./telemetry/export/setup.js";
 export * from "./tools/google_api_tool/index.js";
 import {
+  convertEvalSetToSchema,
   DEFAULT_CRITERIA,
   EVAL_SESSION_ID_PREFIX,
   EvalStatus,
   getEvaluationCriteriaOrDefault,
   getRootAgent,
+  loadEvalSetFromFile,
+  LocalEvalSetResultsManager,
+  LocalEvalSetsManager,
   MISSING_EVAL_DEPENDENCIES_MESSAGE,
+  normalizeEvalCase,
   parseAndGetEvalsToRun,
   RESPONSE_EVALUATION_SCORE_KEY,
   RESPONSE_MATCH_SCORE_KEY,
@@ -141,7 +153,12 @@ import {
   tryGetResetFunc
 } from "./cli/cli_eval.js";
 import { loadDotenvForAgent, walkToRootUntilFound } from "./cli/utils/envs.js";
-import { LOGGING_FORMAT, logToStderr, logToTmpFolder } from "./cli/utils/logs.js";
+import {
+  LOGGING_FORMAT,
+  logToTmpFolder,
+  setupAdkLogger
+} from "./cli/utils/logs.js";
+import { validatePathSegment } from "./cli/utils/path_validation.js";
 export * from "./tools/mcp/index.js";
 export {
   APIHubClient,
@@ -166,11 +183,14 @@ export {
   GcsArtifactService,
   INTERNAL_AUTH_PREFIX,
   IntegrationClient,
+  IntegrationConnectorTool,
   InvocationContext,
   LOAD_WEB_PAGE,
   LOGGING_FORMAT,
   LoadSkillResourceTool,
   LocalEnvironment,
+  LocalEvalSetResultsManager,
+  LocalEvalSetsManager,
   MISSING_EVAL_DEPENDENCIES_MESSAGE,
   OAuth2BearerExchanger,
   OpenAPIToolset,
@@ -194,7 +214,9 @@ export {
   VertexAiSessionService,
   actionRequest,
   actionResponse,
+  agentRuntimeRequestHooks,
   connectorPayload,
+  convertEvalSetToSchema,
   createApiParameter,
   createOperation,
   createOperationRequest,
@@ -203,7 +225,6 @@ export {
   credentialToParam,
   deleteOperation,
   deleteOperationRequest,
-  dictToAuthScheme,
   exchangeCredential,
   executeCustomQueryRequest,
   generateAuthToken,
@@ -222,21 +243,26 @@ export {
   listOperationRequest,
   loadAllSkillsInDir,
   loadDotenvForAgent,
+  loadEvalSetFromFile,
   loadSkillFromDir,
   loadSkillFromZipBuffer,
   loadWebPage,
-  logToStderr,
   logToTmpFolder,
-  openidDictToSchemeCredential,
+  normalizeEvalCase,
+  openidRecordToSchemeCredential,
   openidUrlToSchemeCredential,
   parseAndGetEvalsToRun,
+  recordToAuthScheme,
   runEvals,
-  serviceAccountDictToSchemeCredential,
+  runWithAgentEngineContext,
+  serviceAccountRecordToSchemeCredential,
   serviceAccountSchemeCredential,
+  setupAdkLogger,
   tokenToSchemeCredential,
   tryGetResetFunc,
   updateOperation,
   updateOperationRequest,
+  validatePathSegment,
   validateSkillDir,
   walkToRootUntilFound
 };

package/dist/esm/models/google_llm.js

@@ -12,6 +12,7 @@ import {
   createPartFromText,
   GoogleGenAI
 } from "@google/genai";
+import { adaptComputerUseTool } from "../tools/computer_use/computer_use_toolset.js";
 import { isBrowser, isEnterpriseModeEnabled } from "../utils/env_aware_utils.js";
 import { logger } from "../utils/logger.js";
 import { GoogleLLMVariant } from "../utils/variant_utils.js";
@@ -77,6 +78,7 @@ const _Gemini = class _Gemini extends (_b = BaseLlm, _a = GEMINI_MODEL_SYMBOL, _
    */
   async *generateContentAsync(llmRequest, stream = false, abortSignal) {
     var _a2, _b2;
+    await adaptComputerUseRequest(llmRequest);
     if (this.useInteractionsApi) {
       yield* generateContentViaInteractions(this.apiClient, llmRequest, stream);
       return;
@@ -240,8 +242,14 @@ const _Gemini = class _Gemini extends (_b = BaseLlm, _a = GEMINI_MODEL_SYMBOL, _
         for (const content of llmRequest.contents) {
           if (!content.parts) continue;
           for (const part of content.parts) {
-            removeDisplayNameIfPresent(part.inlineData);
-            removeDisplayNameIfPresent(part.fileData);
+            if (part.inlineData) {
+              part.inlineData = { ...part.inlineData };
+              removeDisplayNameIfPresent(part.inlineData);
+            }
+            if (part.fileData) {
+              part.fileData = { ...part.fileData };
+              removeDisplayNameIfPresent(part.fileData);
+            }
           }
         }
       }
@@ -262,6 +270,29 @@ _Gemini.supportedModels = [
   /projects\/.+\/locations\/.+\/publishers\/google\/models\/gemini.+/
 ];
 let Gemini = _Gemini;
+async function adaptComputerUseRequest(llmRequest) {
+  var _a2, _b2;
+  if (!((_b2 = (_a2 = llmRequest.config) == null ? void 0 : _a2.tools) == null ? void 0 : _b2.some(
+    (tool) => "computerUse" in tool && tool.computerUse
+  ))) {
+    return;
+  }
+  llmRequest.config.systemInstruction = void 0;
+  const waitTool = Object.hasOwn(llmRequest.toolsDict, "wait") ? llmRequest.toolsDict["wait"] : void 0;
+  await adaptComputerUseTool({
+    methodName: "wait",
+    adapter: /* @__PURE__ */ __name((waitFunc) => ({
+      name: "wait_5_seconds",
+      description: "Waits for 5 seconds.",
+      execute: /* @__PURE__ */ __name((_args, toolContext) => waitFunc({ seconds: 5 }, toolContext), "execute")
+    }), "adapter"),
+    llmRequest
+  });
+  if (waitTool && Object.hasOwn(llmRequest.toolsDict, "wait_5_seconds")) {
+    llmRequest.toolsDict["wait"] = waitTool;
+  }
+}
+__name(adaptComputerUseRequest, "adaptComputerUseRequest");
 function removeDisplayNameIfPresent(dataObj) {
   if (dataObj && dataObj.displayName) {
     dataObj.displayName = void 0;

package/dist/esm/models/interactions_utils.js

@@ -342,6 +342,9 @@ function convertToolsConfigToInteractionsFormat(config) {
     if (t.urlContext) {
       interactionTools.push({ type: "url_context" });
     }
+    if (t.computerUse) {
+      interactionTools.push({ type: "computer_use" });
+    }
   }
   return interactionTools;
 }

package/dist/esm/plugins/base_plugin.js

@@ -56,9 +56,9 @@ const _BasePlugin = class _BasePlugin {
    *
    * @param _params.invocationContext The context for the entire invocation, containing
    *     session information, the root agent, etc.
-   * @returns An optional `Event` to be returned to the ADK. Returning a value
-   *     to halt execution of the runner and ends the runner with that event.
-   *     Return `undefined` to proceed normally.
+   * @returns An optional `Content` to be returned to the ADK. Returning a value
+   *     halts execution of the runner and ends the run with an event containing
+   *     that content. Return `undefined` to proceed normally.
    */
   async beforeRunCallback(_params) {
     return;
@@ -81,10 +81,12 @@ const _BasePlugin = class _BasePlugin {
     return;
   }
   /**
-   * Callback executed after an ADK runner run has completed.
+   * Callback executed after successful completion, abort, or early iterator close.
    *
    * This is the final callback in the ADK lifecycle, suitable for cleanup,
-   * final logging, or reporting tasks.
+   * final logging, or reporting tasks. It is skipped when execution fails;
+   * {@link onRunErrorCallback} is called instead. Receiving this callback does
+   * not imply success: recognized cancellation still propagates to the caller.
    *
    * @param _params.invocationContext The context for the entire invocation.
    * @returns undefined
@@ -92,6 +94,23 @@ const _BasePlugin = class _BasePlugin {
   async afterRunCallback(_params) {
     return;
   }
+  /**
+   * Observes an error escaping an agent's execution or lifecycle callbacks.
+   *
+   * Notification-only: return values are ignored and callback failures are
+   * logged. The original execution error always propagates.
+   */
+  async onAgentErrorCallback(_params) {
+  }
+  /**
+   * Observes an error in the run lifecycle, including before/after-run callbacks.
+   *
+   * Notification-only: return values are ignored and callback failures are
+   * logged. The original execution error always propagates. A completion-hook
+   * failure during early iterator close is reported but does not prevent closing.
+   */
+  async onRunErrorCallback(_params) {
+  }
   /**
    * Callback executed before an agent's primary logic is invoked.
    *
@@ -110,14 +129,14 @@ const _BasePlugin = class _BasePlugin {
   /**
    * Callback executed after an agent's primary logic has completed.
    *
-   * This callback can be used to inspect, log, or modify the agent's final
-   * result before it is returned.
+   * This callback can be used to inspect, log, or append an additional event
+   * after the agent's execution completes.
    *
    * @param _params.agent The agent that has just run.
    * @param _params.callbackContext The context for the agent invocation.
-   * @returns An optional `Content` object. If a value is returned, it will
-   *     replace the agent's original result. Returning `undefined` uses the
-   *     original, unmodified result.
+   * @returns An optional `Content` object. If a value is returned, it will be
+   *     emitted as an additional event appended after the agent's execution.
+   *     Returning `undefined` emits no additional content event.
    */
   async afterAgentCallback(_params) {
     return;
@@ -162,8 +181,8 @@ const _BasePlugin = class _BasePlugin {
    *
    * @param _params.callbackContext The context for the current agent call.
    * @param _params.llmRequest The prepared request object to be sent to the model.
-   * @returns An optional value. The interpretation of a non-`undefined`
-   *     trigger an early exit and returns the response immediately. Returning
+   * @returns An optional `LlmResponse`. Returning a non-`undefined` value
+   *     triggers an early exit and returns that response immediately. Returning
    *     `undefined` allows the LLM request to proceed normally.
    */
   async beforeModelCallback(_params) {
@@ -185,7 +204,7 @@ const _BasePlugin = class _BasePlugin {
     return;
   }
   /**
-   * Callback executed when a model call encounters an error.
+   * Callback executed when a model call encounters an `Error`.
    *
    * This callback provides an opportunity to handle model errors gracefully,
    * potentially providing alternative responses or recovery mechanisms.
@@ -193,10 +212,11 @@ const _BasePlugin = class _BasePlugin {
    * @param _params.callbackContext The context for the current agent call.
    * @param _params.llmRequest The request that was sent to the model when the error
    *     occurred.
-   * @param _params.error The exception that was raised during model execution.
-   * @returns An optional LlmResponse. If an LlmResponse is returned, it will be
-   *     used instead of propagating the error. Returning `undefined` allows
-   *     the original error to be raised.
+   * @param _params.error The `Error` instance thrown during model execution.
+   * @returns An optional `LlmResponse`. If an `LlmResponse` is returned, it
+   *     will be used instead of the default error response. Returning
+   *     `undefined` causes an error response/event with `errorCode` and
+   *     `errorMessage` derived from `error` to be yielded.
    */
   async onModelErrorCallback(_params) {
     return;
@@ -246,29 +266,23 @@ const _BasePlugin = class _BasePlugin {
     return;
   }
   /**
-     * Callback executed when a tool call encounters an error.
-      tool: BaseTool;
-      toolArgs: Record<string, unknown>;
-      toolContext: Context;
-      result: Record<string, unknown>;
-    }): Promise<Record<string, unknown> | undefined> {
-      return;
-    }
-  
-    /**
-     * Callback executed when a tool call encounters an error.
-     *
-     * This callback provides an opportunity to handle tool errors gracefully,
-     * potentially providing alternative responses or recovery mechanisms.
-     *
-     * @param _params.tool The tool instance that encountered an error.
-     * @param _params.toolArgs The arguments that were passed to the tool.
-     * @param _params.toolContext The context specific to the tool execution.
-     * @param _params.error The exception that was raised during tool execution.
-     * @returns An optional dictionary. If a dictionary is returned, it will be
-     *     used as the tool response instead of propagating the error. Returning
-     *     `undefined` allows the original error to be raised.
-     */
+   * Callback executed when a tool call encounters an `Error` or cannot be
+   * resolved.
+   *
+   * This callback provides an opportunity to handle tool errors gracefully,
+   * potentially providing alternative responses or recovery mechanisms.
+   *
+   * @param _params.tool The tool instance that encountered an error.
+   * @param _params.toolArgs The arguments that were passed to the tool.
+   * @param _params.toolContext The context specific to the tool execution.
+   * @param _params.error The `Error` that was raised during tool resolution or
+   *     execution.
+   * @returns An optional dictionary. If a dictionary is returned, it will be
+   *     used as the tool response instead of the default error response.
+   *     Returning `undefined` causes `{error: error.message}` to be returned as
+   *     the tool response (unlike adk-python, which re-raises). Non-`Error`
+   *     throwables bypass this callback and become `{error: thrownValue}`.
+   */
   async onToolErrorCallback(_params) {
     return;
   }

package/dist/esm/plugins/plugin_manager.js

@@ -83,6 +83,33 @@ const _PluginManager = class _PluginManager {
     }
     return void 0;
   }
+  /** Notifies every plugin without allowing one failure to hide another. */
+  async runNotificationCallbacks(callback, callbackName) {
+    for (const plugin of this.plugins) {
+      try {
+        await callback(plugin);
+      } catch (error) {
+        logger.error(
+          `Error in plugin '${plugin.name}' during '${callbackName}' callback:`,
+          error
+        );
+      }
+    }
+  }
+  /** Runs the notification-only agent error callback for every plugin. */
+  async runOnAgentErrorCallback(params) {
+    await this.runNotificationCallbacks(
+      (plugin) => plugin.onAgentErrorCallback(params),
+      "onAgentErrorCallback"
+    );
+  }
+  /** Runs the notification-only run error callback for every plugin. */
+  async runOnRunErrorCallback(params) {
+    await this.runNotificationCallbacks(
+      (plugin) => plugin.onRunErrorCallback(params),
+      "onRunErrorCallback"
+    );
+  }
   /**
    * Runs the `onUserMessageCallback` for all plugins.
    */