@google/adk 2.3.0 → 2.5.0

package/dist/cjs/agents/base_agent.js

@@ -30,9 +30,10 @@ __export(base_agent_exports, {
   isBaseAgent: () => isBaseAgent
 });
 module.exports = __toCommonJS(base_agent_exports);
-var import_api = require("@opentelemetry/api");
 var import_event = require("../events/event.js");
-var import_tracing = require("../telemetry/tracing.js");
+var import_instrumentation = require("../telemetry/api/instrumentation.js");
+var import_error_utils = require("../utils/error_utils.js");
+var import_logger = require("../utils/logger.js");
 var import_base_node = require("../workflow/base_node.js");
 var import_context = require("./context.js");
 var import_invocation_context = require("./invocation_context.js");
@@ -122,38 +123,38 @@ const _BaseAgent = class _BaseAgent extends (_b = import_base_node.BaseNode, _a
    * @returns An AsyncGenerator that yields the events generated by the agent.
    */
   async *runAsync(parentContext) {
-    const span = import_tracing.tracer.startSpan(`invoke_agent ${this.name}`);
-    const ctx = import_api.trace.setSpan(import_api.context.active(), span);
-    try {
-      yield* (0, import_tracing.runAsyncGeneratorWithOtelContext)(
-        ctx,
-        this,
-        async function* () {
-          var _a2, _b2;
-          const context2 = this.createInvocationContext(parentContext);
-          const beforeAgentCallbackEvent = await this.handleBeforeAgentCallback(context2);
+    const agentCtx = this;
+    yield* (0, import_instrumentation.recordAgentInvocation)(
+      { agent: this, invocationContext: parentContext },
+      async function* () {
+        var _a2, _b2;
+        const context = agentCtx.createInvocationContext(parentContext);
+        try {
+          const beforeAgentCallbackEvent = await agentCtx.handleBeforeAgentCallback(context);
           if (beforeAgentCallbackEvent) {
             yield beforeAgentCallbackEvent;
           }
-          if (context2.endInvocation || ((_a2 = parentContext.abortSignal) == null ? void 0 : _a2.aborted)) {
+          if (context.endInvocation || ((_a2 = parentContext.abortSignal) == null ? void 0 : _a2.aborted)) {
             return;
           }
-          (0, import_tracing.traceAgentInvocation)({ agent: this, invocationContext: context2 });
-          for await (const event of this.runAsyncImpl(context2)) {
+          for await (const event of agentCtx.runAsyncImpl(context)) {
             yield event;
           }
-          if (context2.endInvocation || ((_b2 = parentContext.abortSignal) == null ? void 0 : _b2.aborted)) {
+          if (context.endInvocation || ((_b2 = parentContext.abortSignal) == null ? void 0 : _b2.aborted)) {
             return;
           }
-          const afterAgentCallbackEvent = await this.handleAfterAgentCallback(context2);
+          const afterAgentCallbackEvent = await agentCtx.handleAfterAgentCallback(context);
           if (afterAgentCallbackEvent) {
             yield afterAgentCallbackEvent;
           }
+        } catch (error) {
+          if (!(0, import_error_utils.isInvocationCancellation)(error, context.abortSignal)) {
+            await agentCtx.handleAgentErrorCallback(context, error);
+          }
+          throw error;
         }
-      );
-    } finally {
-      span.end();
-    }
+      }
+    );
   }
   /**
    * Runs this agent as a workflow node.
@@ -188,36 +189,52 @@ const _BaseAgent = class _BaseAgent extends (_b = import_base_node.BaseNode, _a
    * @returns An AsyncGenerator that yields the events generated by the agent.
    */
   async *runLive(parentContext) {
-    const span = import_tracing.tracer.startSpan(`invoke_agent ${this.name}`);
-    const ctx = import_api.trace.setSpan(import_api.context.active(), span);
-    try {
-      yield* (0, import_tracing.runAsyncGeneratorWithOtelContext)(
-        ctx,
-        this,
-        async function* () {
-          var _a2, _b2;
-          const context2 = this.createInvocationContext(parentContext);
-          const beforeAgentCallbackEvent = await this.handleBeforeAgentCallback(context2);
+    const agentCtx = this;
+    yield* (0, import_instrumentation.recordAgentInvocation)(
+      { agent: this, invocationContext: parentContext },
+      async function* () {
+        var _a2, _b2;
+        const context = agentCtx.createInvocationContext(parentContext);
+        try {
+          const beforeAgentCallbackEvent = await agentCtx.handleBeforeAgentCallback(context);
           if (beforeAgentCallbackEvent) {
             yield beforeAgentCallbackEvent;
           }
-          if (context2.endInvocation || ((_a2 = parentContext.abortSignal) == null ? void 0 : _a2.aborted)) {
+          if (context.endInvocation || ((_a2 = parentContext.abortSignal) == null ? void 0 : _a2.aborted)) {
             return;
           }
-          for await (const event of this.runLiveImpl(context2)) {
+          for await (const event of agentCtx.runLiveImpl(context)) {
             yield event;
           }
-          if (context2.endInvocation || ((_b2 = parentContext.abortSignal) == null ? void 0 : _b2.aborted)) {
+          if (context.endInvocation || ((_b2 = parentContext.abortSignal) == null ? void 0 : _b2.aborted)) {
             return;
           }
-          const afterAgentCallbackEvent = await this.handleAfterAgentCallback(context2);
+          const afterAgentCallbackEvent = await agentCtx.handleAfterAgentCallback(context);
           if (afterAgentCallbackEvent) {
             yield afterAgentCallbackEvent;
           }
+        } catch (error) {
+          if (!(0, import_error_utils.isInvocationCancellation)(error, context.abortSignal)) {
+            await agentCtx.handleAgentErrorCallback(context, error);
+          }
+          throw error;
         }
+      }
+    );
+  }
+  /** Reports execution failures without replacing the original thrown value. */
+  async handleAgentErrorCallback(invocationContext, error) {
+    try {
+      await invocationContext.pluginManager.runOnAgentErrorCallback({
+        agent: this,
+        callbackContext: new import_context.Context({ invocationContext }),
+        error: (0, import_error_utils.toError)(error)
+      });
+    } catch (callbackError) {
+      import_logger.logger.error(
+        "Agent error notification failed; preserving the original error.",
+        callbackError
       );
-    } finally {
-      span.end();
     }
   }
   /**
@@ -259,6 +276,22 @@ const _BaseAgent = class _BaseAgent extends (_b = import_base_node.BaseNode, _a
       agent: this
     });
   }
+  /**
+   * The resolved beforeAgentCallback field as a list of SingleAgentCallback.
+   *
+   * This method is only for use by Agent Development Kit.
+   */
+  get canonicalBeforeAgentCallbacks() {
+    return this.beforeAgentCallback;
+  }
+  /**
+   * The resolved afterAgentCallback field as a list of SingleAgentCallback.
+   *
+   * This method is only for use by Agent Development Kit.
+   */
+  get canonicalAfterAgentCallbacks() {
+    return this.afterAgentCallback;
+  }
   /**
    * Runs the before agent callback if it exists.
    *
@@ -267,27 +300,40 @@ const _BaseAgent = class _BaseAgent extends (_b = import_base_node.BaseNode, _a
    *     generated.
    */
   async handleBeforeAgentCallback(invocationContext) {
-    var _a2;
-    if (this.beforeAgentCallback.length === 0) {
+    var _a2, _b2, _c;
+    const hasPlugins = Boolean((_a2 = invocationContext.pluginManager) == null ? void 0 : _a2.hasPlugins);
+    if (!hasPlugins && this.canonicalBeforeAgentCallbacks.length === 0) {
       return void 0;
     }
     const callbackContext = new import_context.Context({ invocationContext });
-    for (const callback of this.beforeAgentCallback) {
-      const content = await callback(callbackContext);
-      if ((_a2 = invocationContext.abortSignal) == null ? void 0 : _a2.aborted) {
-        return;
-      }
-      if (content) {
-        invocationContext.endInvocation = true;
-        return (0, import_event.createEvent)({
-          invocationId: invocationContext.invocationId,
-          author: this.name,
-          branch: invocationContext.branch,
-          content,
-          actions: callbackContext.eventActions
-        });
+    let content = hasPlugins ? await invocationContext.pluginManager.runBeforeAgentCallback({
+      agent: this,
+      callbackContext
+    }) : void 0;
+    if ((_b2 = invocationContext.abortSignal) == null ? void 0 : _b2.aborted) {
+      return;
+    }
+    if (!content) {
+      for (const callback of this.canonicalBeforeAgentCallbacks) {
+        content = await callback(callbackContext);
+        if ((_c = invocationContext.abortSignal) == null ? void 0 : _c.aborted) {
+          return;
+        }
+        if (content) {
+          break;
+        }
       }
     }
+    if (content) {
+      invocationContext.endInvocation = true;
+      return (0, import_event.createEvent)({
+        invocationId: invocationContext.invocationId,
+        author: this.name,
+        branch: invocationContext.branch,
+        content,
+        actions: callbackContext.eventActions
+      });
+    }
     if (callbackContext.state.hasDelta()) {
       return (0, import_event.createEvent)({
         invocationId: invocationContext.invocationId,
@@ -306,26 +352,39 @@ const _BaseAgent = class _BaseAgent extends (_b = import_base_node.BaseNode, _a
    *     generated.
    */
   async handleAfterAgentCallback(invocationContext) {
-    var _a2;
-    if (this.afterAgentCallback.length === 0) {
+    var _a2, _b2, _c;
+    const hasPlugins = Boolean((_a2 = invocationContext.pluginManager) == null ? void 0 : _a2.hasPlugins);
+    if (!hasPlugins && this.canonicalAfterAgentCallbacks.length === 0) {
       return void 0;
     }
     const callbackContext = new import_context.Context({ invocationContext });
-    for (const callback of this.afterAgentCallback) {
-      const content = await callback(callbackContext);
-      if ((_a2 = invocationContext.abortSignal) == null ? void 0 : _a2.aborted) {
-        return;
-      }
-      if (content) {
-        return (0, import_event.createEvent)({
-          invocationId: invocationContext.invocationId,
-          author: this.name,
-          branch: invocationContext.branch,
-          content,
-          actions: callbackContext.eventActions
-        });
+    let content = hasPlugins ? await invocationContext.pluginManager.runAfterAgentCallback({
+      agent: this,
+      callbackContext
+    }) : void 0;
+    if ((_b2 = invocationContext.abortSignal) == null ? void 0 : _b2.aborted) {
+      return;
+    }
+    if (!content) {
+      for (const callback of this.canonicalAfterAgentCallbacks) {
+        content = await callback(callbackContext);
+        if ((_c = invocationContext.abortSignal) == null ? void 0 : _c.aborted) {
+          return;
+        }
+        if (content) {
+          break;
+        }
       }
     }
+    if (content) {
+      return (0, import_event.createEvent)({
+        invocationId: invocationContext.invocationId,
+        author: this.name,
+        branch: invocationContext.branch,
+        content,
+        actions: callbackContext.eventActions
+      });
+    }
     if (callbackContext.state.hasDelta()) {
       return (0, import_event.createEvent)({
         invocationId: invocationContext.invocationId,

package/dist/cjs/agents/functions.js

@@ -51,13 +51,14 @@ var import_lodash_es = require("lodash-es");
 var import_event = require("../events/event.js");
 var import_event_actions = require("../events/event_actions.js");
 var import_base_tool = require("../tools/base_tool.js");
+var import_computer_use_tool = require("../tools/computer_use/computer_use_tool.js");
 var import_function_tool = require("../tools/function_tool.js");
 var import_logger = require("../utils/logger.js");
 var import_task = require("../utils/task.js");
 var import_active_streaming_tool = require("./active_streaming_tool.js");
 var import_context = require("./context.js");
 var import_framework_function_calls = require("./framework_function_calls.js");
-var import_tracing = require("../telemetry/tracing.js");
+var import_instrumentation = require("../telemetry/api/instrumentation.js");
 var import_event2 = require("../events/event.js");
 var import_framework_function_calls2 = require("./framework_function_calls.js");
 /**
@@ -165,28 +166,45 @@ function generateRequestConfirmationEvent({
 }
 __name(generateRequestConfirmationEvent, "generateRequestConfirmationEvent");
 async function callToolAsync(tool, args, toolContext) {
-  return import_tracing.tracer.startActiveSpan(`execute_tool ${tool.name}`, async (span) => {
-    try {
+  return (0, import_instrumentation.recordToolExecution)(
+    { tool, args, invocationContext: toolContext.invocationContext },
+    async (scope) => {
       import_logger.logger.debug(`callToolAsync ${tool.name}`);
       const result = await tool.runAsync({ args, toolContext });
-      (0, import_tracing.traceToolCall)({
-        tool,
-        args,
+      scope.recordSuccess({
         functionResponseEvent: buildResponseEvent(
           tool,
           result,
           toolContext,
           toolContext.invocationContext
         ),
-        invocationContext: toolContext.invocationContext
+        rawResult: result
       });
       return result;
-    } finally {
-      span.end();
     }
-  });
+  );
 }
 __name(callToolAsync, "callToolAsync");
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+function buildFunctionResponse({
+  tool,
+  id,
+  response
+}) {
+  const image = (0, import_computer_use_tool.isComputerUseTool)(tool) ? response == null ? void 0 : response["image"] : void 0;
+  if (typeof image !== "object" || image === null || !("data" in image) || !("mimetype" in image) || typeof image.data !== "string" || typeof image.mimetype !== "string" || !BASE64.test(image.data)) {
+    return { id, name: tool.name, response };
+  }
+  const rest = { ...response };
+  delete rest["image"];
+  return {
+    id,
+    name: tool.name,
+    response: rest,
+    parts: [{ inlineData: { data: image.data, mimeType: image.mimetype } }]
+  };
+}
+__name(buildFunctionResponse, "buildFunctionResponse");
 function buildResponseEvent(tool, functionResult, toolContext, invocationContext) {
   let responseResult;
   if (typeof functionResult !== "object" || functionResult == null) {
@@ -197,11 +215,11 @@ function buildResponseEvent(tool, functionResult, toolContext, invocationContext
     responseResult = functionResult;
   }
   const partFunctionResponse = {
-    functionResponse: {
-      name: tool.name,
-      response: responseResult,
-      id: toolContext.functionCallId
-    }
+    functionResponse: buildFunctionResponse({
+      tool,
+      id: toolContext.functionCallId,
+      response: responseResult
+    })
   };
   const content = {
     role: "user",
@@ -304,38 +322,35 @@ async function answerUnresolvableCall({
   toolsDict,
   toolContext
 }) {
-  return import_tracing.tracer.startActiveSpan(
-    `execute_tool ${functionCall.name || "<unnamed>"}`,
-    async (span) => {
-      var _a2, _b2;
-      try {
-        const toolName = functionCall.name || "<unnamed>";
-        const error = new Error(
-          `Function ${toolName} is not found in the toolsDict.`
-        );
-        const tool = new ToolNotFoundPlaceholder(toolName, error);
-        const onToolErrorResponse = await invocationContext.pluginManager.runOnToolErrorCallback({
-          tool,
-          toolArgs: (_a2 = functionCall.args) != null ? _a2 : {},
-          toolContext,
-          error
-        });
-        if (onToolErrorResponse == null) {
-          const callableTools = Object.keys(toolsDict);
-          import_logger.logger.warn(
-            `Could not resolve tool '${toolName}' for function call '${(_b2 = functionCall.id) != null ? _b2 : ""}'. Callable tools: ${callableTools.length ? callableTools.join(", ") : "(none)"}.
+  var _a2;
+  const toolName = functionCall.name || "<unnamed>";
+  const error = new Error(
+    `Function ${toolName} is not found in the toolsDict.`
+  );
+  const tool = new ToolNotFoundPlaceholder(toolName, error);
+  return (0, import_instrumentation.recordToolExecution)(
+    { tool, args: (_a2 = functionCall.args) != null ? _a2 : {}, invocationContext },
+    async () => {
+      var _a3, _b2;
+      const onToolErrorResponse = await invocationContext.pluginManager.runOnToolErrorCallback({
+        tool,
+        toolArgs: (_a3 = functionCall.args) != null ? _a3 : {},
+        toolContext,
+        error
+      });
+      if (onToolErrorResponse == null) {
+        const callableTools = Object.keys(toolsDict);
+        import_logger.logger.warn(
+          `Could not resolve tool '${toolName}' for function call '${(_b2 = functionCall.id) != null ? _b2 : ""}'. Callable tools: ${callableTools.length ? callableTools.join(", ") : "(none)"}.
 ` + RESOLUTION_FAILURE_CAUSES
-          );
-        }
-        return buildResponseEvent(
-          tool,
-          onToolErrorResponse != null ? onToolErrorResponse : { error: error.message },
-          toolContext,
-          invocationContext
         );
-      } finally {
-        span.end();
       }
+      return buildResponseEvent(
+        tool,
+        onToolErrorResponse != null ? onToolErrorResponse : { error: error.message },
+        toolContext,
+        invocationContext
+      );
     }
   );
 }
@@ -476,11 +491,11 @@ async function handleFunctionCallList({
       invocationId: invocationContext.invocationId,
       author: toolEventAuthor(invocationContext),
       content: (0, import_genai.createUserContent)({
-        functionResponse: {
+        functionResponse: buildFunctionResponse({
+          tool,
           id: toolContext.functionCallId,
-          name: tool.name,
           response: functionResponse
-        }
+        })
       }),
       actions: toolContext.actions,
       branch: invocationContext.branch
@@ -494,18 +509,8 @@ async function handleFunctionCallList({
     functionResponseEvents
   );
   if (functionResponseEvents.length > 1) {
-    import_tracing.tracer.startActiveSpan("execute_tool (merged)", (span) => {
-      try {
-        import_logger.logger.debug("execute_tool (merged)");
-        (0, import_tracing.traceMergedToolCalls)({
-          responseEventId: mergedEvent.id,
-          functionResponseEvent: mergedEvent,
-          invocationContext
-        });
-      } finally {
-        span.end();
-      }
-    });
+    import_logger.logger.debug("execute_tool (merged)");
+    (0, import_instrumentation.recordMergedToolCalls)({ responseEventId: mergedEvent.id });
   }
   return mergedEvent;
 }

package/dist/cjs/agents/instructions.js

@@ -29,6 +29,7 @@ __export(instructions_exports, {
 });
 module.exports = __toCommonJS(instructions_exports);
 var import_state = require("../sessions/state.js");
+var import_load_artifacts_tool = require("../tools/load_artifacts_tool.js");
 /**
  * @license
  * Copyright 2025 Google LLC
@@ -62,10 +63,13 @@ async function resolveKey(key, isOptional, rawMatch, readonlyContext) {
       }
       throw new Error(`Artifact ${fileName} not found.`);
     }
-    return formatValue(artifact, true);
+    return formatValue(
+      (0, import_load_artifacts_tool.asSafePartForLlm)(artifact, fileName, { inlineMediaAsPlaceholder: true }),
+      true
+    );
   }
   if (isValidStateName(key)) {
-    if (key in invocationContext.session.state) {
+    if (Object.hasOwn(invocationContext.session.state, key)) {
       return formatValue(invocationContext.session.state[key], false);
     }
     if (isOptional) {
@@ -187,14 +191,12 @@ async function injectSessionState(template, readonlyContext) {
   return result.join("");
 }
 __name(injectSessionState, "injectSessionState");
-const isIdentifierPattern = /* @__PURE__ */ (() => {
-  return /^[a-zA-Z_][a-zA-Z0-9_]*$/;
-})();
+const IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 function isIdentifier(s) {
   if (s === "" || s === void 0) {
     return false;
   }
-  return isIdentifierPattern.test(s);
+  return IDENTIFIER_PATTERN.test(s);
 }
 __name(isIdentifier, "isIdentifier");
 const VALID_PREFIXES = [import_state.State.APP_PREFIX, import_state.State.USER_PREFIX, import_state.State.TEMP_PREFIX];

package/dist/cjs/agents/invocation_context.js

@@ -32,7 +32,7 @@ __export(invocation_context_exports, {
   requireAgent: () => requireAgent
 });
 module.exports = __toCommonJS(invocation_context_exports);
-var import_env_aware_utils = require("../utils/env_aware_utils.js");
+var import_id_provider = require("../utils/id_provider.js");
 /**
  * @license
  * Copyright 2025 Google LLC
@@ -141,7 +141,7 @@ const _InvocationContext = class _InvocationContext {
 __name(_InvocationContext, "InvocationContext");
 let InvocationContext = _InvocationContext;
 function newInvocationContextId() {
-  return `e-${(0, import_env_aware_utils.randomUUID)()}`;
+  return `e-${(0, import_id_provider.newId)()}`;
 }
 __name(newInvocationContextId, "newInvocationContextId");
 function requireAgent(ctx) {