@google/adk 2.3.0 → 2.5.0

package/dist/cjs/telemetry/export/request_driven_metric_reader.js

@@ -0,0 +1,303 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+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 });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var request_driven_metric_reader_exports = {};
+__export(request_driven_metric_reader_exports, {
+  MIN_EXPORT_INTERVAL_MS: () => MIN_EXPORT_INTERVAL_MS,
+  RequestDrivenMetricReader: () => RequestDrivenMetricReader,
+  isRequestDrivenMetricReader: () => isRequestDrivenMetricReader
+});
+module.exports = __toCommonJS(request_driven_metric_reader_exports);
+var import_api = require("@opentelemetry/api");
+var import_sdk_metrics = require("@opentelemetry/sdk-metrics");
+var import_error_utils = require("../../utils/error_utils.js");
+var import_logger = require("../../utils/logger.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a, _b;
+const MIN_EXPORT_INTERVAL_MS = 5e3;
+const FLOOR_ENV_VAR = "GOOGLE_CLOUD_AGENT_ENGINE_METRICS_COLLECTION_INTERVAL_FLOOR_MS";
+const EXPORT_INTERVAL_ENV_VAR = "OTEL_METRIC_EXPORT_INTERVAL";
+const EXPORT_TIMEOUT_ENV_VAR = "OTEL_METRIC_EXPORT_TIMEOUT";
+const DEFAULT_EXPORT_INTERVAL_MS = 6e4;
+const DEFAULT_EXPORT_TIMEOUT_MS = 3e4;
+const OVERDUE_PERIODS = 1.5;
+const INFERENCE_START_HOOK_KEY = /* @__PURE__ */ Symbol.for(
+  "google.adk.telemetry.inferenceStartHook"
+);
+const SUPPRESS_TRACING_KEY = (0, import_api.createContextKey)(
+  "OpenTelemetry SDK Context Key SUPPRESS_TRACING"
+);
+const EXPORT_RESULT_SUCCESS = 0;
+const REQUEST_DRIVEN_METRIC_READER_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "google.adk.requestDrivenMetricReader"
+);
+function isRequestDrivenMetricReader(obj) {
+  return typeof obj === "object" && obj !== null && REQUEST_DRIVEN_METRIC_READER_SIGNATURE_SYMBOL in obj;
+}
+__name(isRequestDrivenMetricReader, "isRequestDrivenMetricReader");
+const _RequestDrivenMetricReader = class _RequestDrivenMetricReader extends (_b = import_sdk_metrics.MetricReader, _a = REQUEST_DRIVEN_METRIC_READER_SIGNATURE_SYMBOL, _b) {
+  constructor({
+    exporter,
+    exportIntervalMillis,
+    exportTimeoutMillis,
+    floorMillis,
+    now = /* @__PURE__ */ __name(() => performance.now(), "now")
+  }) {
+    var _a2, _b2;
+    super({
+      aggregationSelector: (_a2 = exporter.selectAggregation) == null ? void 0 : _a2.bind(exporter),
+      aggregationTemporalitySelector: (_b2 = exporter.selectAggregationTemporality) == null ? void 0 : _b2.bind(exporter)
+    });
+    this[_a] = true;
+    this.inferenceStartHook = /* @__PURE__ */ __name(() => this.onInferenceStart(), "inferenceStartHook");
+    this.inFlight = 0;
+    this.isShutdown = false;
+    this.warnedNoRequest = false;
+    this.exporter = exporter;
+    this.now = now;
+    this.periodMillis = resolveMillis({
+      name: EXPORT_INTERVAL_ENV_VAR,
+      explicit: exportIntervalMillis,
+      fallback: DEFAULT_EXPORT_INTERVAL_MS,
+      allowZero: false
+    });
+    this.exportTimeoutMillis = resolveMillis({
+      name: EXPORT_TIMEOUT_ENV_VAR,
+      explicit: exportTimeoutMillis,
+      fallback: DEFAULT_EXPORT_TIMEOUT_MS,
+      allowZero: false
+    });
+    this.floorMillis = resolveMillis({
+      name: FLOOR_ENV_VAR,
+      explicit: floorMillis,
+      fallback: MIN_EXPORT_INTERVAL_MS,
+      allowZero: true
+    });
+    this.nextDue = this.now() + this.periodMillis;
+  }
+  /** Marks a request as started, and collects if a guidepost has passed. */
+  onRequestStart() {
+    try {
+      const now = this.now();
+      const overlap = this.inFlight >= 1;
+      if (!overlap) {
+        this.busyStart = now;
+      }
+      this.inFlight += 1;
+      if (!this.canCollect() || !overlap || now < this.nextDue) {
+        return;
+      }
+      if (this.floorAllows(now)) {
+        this.startCollect(now);
+        return;
+      }
+      this.nextDue += this.periodMillis;
+    } catch (error) {
+      import_logger.logger.warn(`Metric request-start hook failed: ${(0, import_error_utils.formatError)(error)}`);
+    }
+  }
+  /**
+   * Marks a request as ended. Collects when no request is left in flight and
+   * the floor allows it, and resolves once any running collect has exported.
+   */
+  async onRequestEnd() {
+    try {
+      const now = this.now();
+      this.inFlight = Math.max(0, this.inFlight - 1);
+      if (this.inFlight === 0 && this.canCollect() && this.floorAllows(now)) {
+        this.startCollect(now);
+      }
+    } catch (error) {
+      import_logger.logger.warn(`Metric request-end hook failed: ${(0, import_error_utils.formatError)(error)}`);
+    }
+    await this.runningCollect;
+  }
+  /** Collects at a model-call start if the busy period is overdue. */
+  onInferenceStart() {
+    try {
+      if (this.inFlight === 0) {
+        if (!this.warnedNoRequest && !this.isShutdown) {
+          this.warnedNoRequest = true;
+          import_logger.logger.warn(
+            "A model call started with no active request in RequestDrivenMetricReader. Wrap each request with agentRuntimeRequestHooks(otelHooks) so metrics are collected and exported while requests hold the CPU."
+          );
+        }
+        return;
+      }
+      const now = this.now();
+      if (this.canCollect() && this.isOverdue(now) && this.floorAllows(now)) {
+        this.startCollect(now);
+      }
+    } catch (error) {
+      import_logger.logger.warn(`Metric model-call hook failed: ${(0, import_error_utils.formatError)(error)}`);
+    }
+  }
+  /**
+   * Registers the model-call start hook when a provider initializes this
+   * reader.
+   *
+   * Because the hook uses a single process-global slot where the last
+   * registered reader wins, only a single active reader is supported.
+   */
+  onInitialized() {
+    Reflect.set(globalThis, INFERENCE_START_HOOK_KEY, this.inferenceStartHook);
+  }
+  /** Shuts down the reader, exports remaining metrics, and cleans up hooks. */
+  async onShutdown() {
+    this.isShutdown = true;
+    if (Reflect.get(globalThis, INFERENCE_START_HOOK_KEY) === this.inferenceStartHook) {
+      Reflect.deleteProperty(globalThis, INFERENCE_START_HOOK_KEY);
+    }
+    await this.runningCollect;
+    await this.runExclusive();
+    await this.exporter.shutdown();
+  }
+  /** Flushes any in-flight and pending metric exports. */
+  async onForceFlush() {
+    await this.runningCollect;
+    await this.runExclusive();
+    await this.exporter.forceFlush();
+  }
+  canCollect() {
+    return this.runningCollect === void 0 && !this.isShutdown;
+  }
+  floorAllows(now) {
+    return this.lastCollect === void 0 || now - this.lastCollect >= this.floorMillis;
+  }
+  /**
+   * Returns whether the current busy period has gone 1.5 periods without a
+   * collect. A collect from an earlier busy period does not count, so a short
+   * request after an idle gap is never overdue: collecting at its model call
+   * would set the floor and mute the drain that carries its points.
+   */
+  isOverdue(now) {
+    var _a2;
+    if (this.busyStart === void 0) {
+      return false;
+    }
+    const since = Math.max(this.busyStart, (_a2 = this.lastCollect) != null ? _a2 : -Infinity);
+    return now - since >= OVERDUE_PERIODS * this.periodMillis;
+  }
+  /** Starts a collect, and moves the guidepost grid past `now`. */
+  startCollect(now) {
+    if (now >= this.nextDue) {
+      const missed = Math.floor((now - this.nextDue) / this.periodMillis) + 1;
+      this.nextDue += missed * this.periodMillis;
+    }
+    this.lastCollect = now;
+    void this.runExclusive();
+  }
+  /** Runs one collect and export as the running collect. Never rejects. */
+  runExclusive() {
+    const run = this.collectAndExport().finally(() => {
+      if (this.runningCollect === run) {
+        this.runningCollect = void 0;
+      }
+    });
+    this.runningCollect = run;
+    return run;
+  }
+  async collectAndExport() {
+    var _a2, _b2;
+    try {
+      const { resourceMetrics, errors } = await this.collect({
+        timeoutMillis: this.exportTimeoutMillis
+      });
+      for (const error of errors) {
+        import_logger.logger.warn(`Metric collection reported: ${(0, import_error_utils.formatError)(error)}`);
+      }
+      if (resourceMetrics.resource.asyncAttributesPending) {
+        await ((_b2 = (_a2 = resourceMetrics.resource).waitForAsyncAttributes) == null ? void 0 : _b2.call(_a2));
+      }
+      if (resourceMetrics.scopeMetrics.length === 0) {
+        return;
+      }
+      await this.export(resourceMetrics);
+    } catch (error) {
+      import_logger.logger.warn(`Request-driven metric export failed: ${(0, import_error_utils.formatError)(error)}`);
+    }
+  }
+  async export(resourceMetrics) {
+    let timer;
+    const timedOut = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(
+          new Error(
+            `Metric export timed out after ${this.exportTimeoutMillis} ms.`
+          )
+        );
+      }, this.exportTimeoutMillis);
+    });
+    const exported = new Promise((resolve) => {
+      import_api.context.with(
+        import_api.context.active().setValue(SUPPRESS_TRACING_KEY, true),
+        () => this.exporter.export(resourceMetrics, resolve)
+      );
+    });
+    try {
+      const result = await Promise.race([exported, timedOut]);
+      if (result.code !== EXPORT_RESULT_SUCCESS) {
+        throw new Error(
+          `Metric exporter reported a failure: ${(0, import_error_utils.formatError)(result.error)}`
+        );
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+__name(_RequestDrivenMetricReader, "RequestDrivenMetricReader");
+let RequestDrivenMetricReader = _RequestDrivenMetricReader;
+function resolveMillis({
+  name,
+  explicit,
+  fallback,
+  allowZero
+}) {
+  const raw = explicit != null ? explicit : process.env[name];
+  if (raw === void 0) {
+    return fallback;
+  }
+  const value = typeof raw === "number" ? raw : Number(raw.trim() || NaN);
+  const inRange = allowZero ? value >= 0 : value > 0;
+  if (Number.isFinite(value) && inRange) {
+    return value;
+  }
+  import_logger.logger.warn(
+    `Found invalid value for ${name}=${JSON.stringify(raw)}, using default ${fallback}.`
+  );
+  return fallback;
+}
+__name(resolveMillis, "resolveMillis");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MIN_EXPORT_INTERVAL_MS,
+  RequestDrivenMetricReader,
+  isRequestDrivenMetricReader
+});

package/dist/cjs/telemetry/{setup.js → export/setup.js}

@@ -44,8 +44,24 @@ var import_sdk_trace_node = require("@opentelemetry/sdk-trace-node");
  * SPDX-License-Identifier: Apache-2.0
  */
 function maybeSetOtelProviders(otelHooksToSetup = [], otelResource) {
+  const tracerAlreadySet = isTracerProviderRegistered();
+  const meterAlreadySet = isMeterProviderRegistered();
+  const loggerAlreadySet = isLoggerProviderRegistered();
+  if (tracerAlreadySet && meterAlreadySet && loggerAlreadySet) {
+    return;
+  }
+  const exportersConfig = getOtelExportersConfig();
+  if (tracerAlreadySet) {
+    exportersConfig.enableTracing = false;
+  }
+  if (meterAlreadySet) {
+    exportersConfig.enableMetrics = false;
+  }
+  if (loggerAlreadySet) {
+    exportersConfig.enableLogging = false;
+  }
   const resource = otelResource || getOtelResource();
-  const allHooks = [...otelHooksToSetup, getOtelExporters()];
+  const allHooks = [...otelHooksToSetup, getOtelExporters(exportersConfig)];
   const spanProcessors = allHooks.flatMap(
     (hooks) => hooks.spanProcessors || []
   );
@@ -53,22 +69,21 @@ function maybeSetOtelProviders(otelHooksToSetup = [], otelResource) {
   const logRecordProcessors = allHooks.flatMap(
     (hooks) => hooks.logRecordProcessors || []
   );
-  if (spanProcessors.length > 0) {
+  if (!tracerAlreadySet && spanProcessors.length > 0) {
     const tracerProvider = new import_sdk_trace_node.NodeTracerProvider({
       resource,
       spanProcessors
     });
     tracerProvider.register();
-    import_api.trace.setGlobalTracerProvider(tracerProvider);
   }
-  if (metricReaders.length > 0) {
+  if (!meterAlreadySet && metricReaders.length > 0) {
     const meterProvider = new import_sdk_metrics.MeterProvider({
       readers: metricReaders,
       resource
     });
     import_api.metrics.setGlobalMeterProvider(meterProvider);
   }
-  if (logRecordProcessors.length > 0) {
+  if (!loggerAlreadySet && logRecordProcessors.length > 0) {
     const loggerProvider = new import_sdk_logs.LoggerProvider({
       resource,
       processors: logRecordProcessors
@@ -79,7 +94,7 @@ function maybeSetOtelProviders(otelHooksToSetup = [], otelResource) {
 __name(maybeSetOtelProviders, "maybeSetOtelProviders");
 function getOtelResource() {
   return (0, import_resources.detectResources)({
-    detectors: []
+    detectors: [import_resources.envDetector]
   });
 }
 __name(getOtelResource, "getOtelResource");
@@ -104,6 +119,57 @@ function getOtelExporters(config = getOtelExportersConfig()) {
   };
 }
 __name(getOtelExporters, "getOtelExporters");
+function isTracerProviderRegistered() {
+  var _a, _b, _c, _d, _e, _f, _g;
+  const provider = (_b = (_a = import_api.trace).getTracerProvider) == null ? void 0 : _b.call(_a);
+  if (!provider) {
+    return false;
+  }
+  const noopDelegate = typeof import_api.ProxyTracerProvider === "function" ? (_d = (_c = new import_api.ProxyTracerProvider()) == null ? void 0 : _c.getDelegate) == null ? void 0 : _d.call(_c) : void 0;
+  const getDelegate = provider.getDelegate;
+  if (typeof getDelegate === "function") {
+    const delegate = getDelegate.call(provider);
+    if (!delegate) {
+      return false;
+    }
+    if (noopDelegate && delegate === noopDelegate) {
+      return false;
+    }
+    return ((_e = delegate.constructor) == null ? void 0 : _e.name) !== "NoopTracerProvider";
+  }
+  if (noopDelegate && provider === noopDelegate) {
+    return false;
+  }
+  return ((_f = provider.constructor) == null ? void 0 : _f.name) !== "ProxyTracerProvider" && ((_g = provider.constructor) == null ? void 0 : _g.name) !== "NoopTracerProvider";
+}
+__name(isTracerProviderRegistered, "isTracerProviderRegistered");
+function isMeterProviderRegistered() {
+  var _a, _b, _c;
+  const provider = (_b = (_a = import_api.metrics).getMeterProvider) == null ? void 0 : _b.call(_a);
+  if (!provider) {
+    return false;
+  }
+  const noopMeter = typeof import_api.createNoopMeter === "function" ? (0, import_api.createNoopMeter)() : void 0;
+  if (noopMeter && typeof provider.getMeter === "function") {
+    if (provider.getMeter("adk") === noopMeter) {
+      return false;
+    }
+  }
+  return ((_c = provider.constructor) == null ? void 0 : _c.name) !== "NoopMeterProvider";
+}
+__name(isMeterProviderRegistered, "isMeterProviderRegistered");
+function isLoggerProviderRegistered() {
+  var _a, _b, _c, _d;
+  const provider = (_b = (_a = import_api_logs.logs).getLoggerProvider) == null ? void 0 : _b.call(_a);
+  if (!provider) {
+    return false;
+  }
+  if (typeof provider._getDelegate === "function") {
+    return provider._delegate !== void 0;
+  }
+  return ((_c = provider.constructor) == null ? void 0 : _c.name) !== "ProxyLoggerProvider" && ((_d = provider.constructor) == null ? void 0 : _d.name) !== "NoopLoggerProvider";
+}
+__name(isLoggerProviderRegistered, "isLoggerProviderRegistered");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   maybeSetOtelProviders

package/dist/cjs/tools/agent_tool.js

@@ -30,6 +30,7 @@ __export(agent_tool_exports, {
 });
 module.exports = __toCommonJS(agent_tool_exports);
 var import_genai = require("@google/genai");
+var import_lodash_es = require("lodash-es");
 var import_llm_agent = require("../agents/llm_agent.js");
 var import_in_memory_memory_service = require("../memory/in_memory_memory_service.js");
 var import_runner = require("../runner/runner.js");
@@ -156,12 +157,18 @@ const _AgentTool = class _AgentTool extends (_b = import_base_tool.BaseTool, _a
       memoryService: (_b2 = toolContext.invocationContext.memoryService) != null ? _b2 : new import_in_memory_memory_service.InMemoryMemoryService(),
       credentialService: toolContext.invocationContext.credentialService
     });
+    const parentState = toolContext.state.toRecord();
     const session = await runner.sessionService.getOrCreateSession({
       appName: this.agent.name,
       userId: toolContext.invocationContext.userId,
       sessionId: toolContext.invocationContext.session.id,
-      state: toolContext.state.toRecord()
+      state: parentState
     });
+    const stateDelta = Object.fromEntries(
+      Object.entries(parentState).filter(
+        ([key, value]) => !key.startsWith(import_state.State.TEMP_PREFIX) && !(0, import_lodash_es.isEqual)(session.state[key], value)
+      )
+    );
     if ((_c = toolContext.abortSignal) == null ? void 0 : _c.aborted) {
       return "";
     }
@@ -170,6 +177,7 @@ const _AgentTool = class _AgentTool extends (_b = import_base_tool.BaseTool, _a
       userId: session.userId,
       sessionId: session.id,
       newMessage: content,
+      stateDelta: Object.keys(stateDelta).length > 0 ? stateDelta : void 0,
       abortSignal: toolContext.abortSignal
     })) {
       if ((_d = toolContext.abortSignal) == null ? void 0 : _d.aborted) {

package/dist/cjs/tools/apihub_tool/apihub_toolset.js

@@ -46,7 +46,7 @@ __export(apihub_toolset_exports, {
   APIHubToolset: () => APIHubToolset
 });
 module.exports = __toCommonJS(apihub_toolset_exports);
-var import_js_yaml = __toESM(require("js-yaml"), 1);
+var yaml = __toESM(require("js-yaml"), 1);
 var import_case_utils = require("../../utils/case_utils.js");
 var import_experimental = require("../../utils/experimental.js");
 var import_base_toolset = require("../base_toolset.js");
@@ -59,15 +59,15 @@ var import_apihub_client = require("./clients/apihub_client.js");
  */
 let APIHubToolset = class extends import_base_toolset.BaseToolset {
   constructor(options) {
-    var _a, _b, _c, _d;
-    super([]);
-    this.name = (_a = options.name) != null ? _a : "";
-    this.description = (_b = options.description) != null ? _b : "";
+    var _a, _b, _c, _d, _e;
+    super((_a = options.toolFilter) != null ? _a : []);
+    this.name = (_b = options.name) != null ? _b : "";
+    this.description = (_c = options.description) != null ? _c : "";
     this.apihubResourceName = options.apihubResourceName;
-    this.lazyLoadSpec = (_c = options.lazyLoadSpec) != null ? _c : false;
+    this.lazyLoadSpec = (_d = options.lazyLoadSpec) != null ? _d : false;
     this.authScheme = options.authScheme;
     this.authCredential = options.authCredential;
-    this.apihubClient = (_d = options.apihubClient) != null ? _d : new import_apihub_client.APIHubClient({
+    this.apihubClient = (_e = options.apihubClient) != null ? _e : new import_apihub_client.APIHubClient({
       accessToken: options.accessToken,
       serviceAccountJson: options.serviceAccountJson
     });
@@ -86,21 +86,12 @@ let APIHubToolset = class extends import_base_toolset.BaseToolset {
     const toolset = await this.loadToolset();
     return toolset ? toolset.getTools(context) : [];
   }
-  /**
-   * Returns the tool with the given name, or `undefined` when the spec
-   * produced no such tool.
-   *
-   * Unlike `OpenAPIToolset.getTool`, the result is a Promise, because the spec
-   * may still be loading.
-   *
-   * @param name The tool name, which is the operation ID in snake_case.
-   * @throws When the spec cannot be fetched or is not valid YAML or JSON.
-   */
-  async getTool(name) {
-    const toolset = await this.loadToolset();
-    return toolset == null ? void 0 : toolset.getTool(name);
-  }
   async close() {
+    if (!this.toolsetPromise) {
+      return;
+    }
+    const toolset = await this.toolsetPromise.catch(() => void 0);
+    await (toolset == null ? void 0 : toolset.close());
   }
   loadToolset() {
     if (!this.toolsetPromise) {
@@ -119,7 +110,10 @@ let APIHubToolset = class extends import_base_toolset.BaseToolset {
     const spec = await this.apihubClient.getSpecContent(
       this.apihubResourceName
     );
-    const specDict = import_js_yaml.default.load(spec);
+    if (!spec.trim()) {
+      return void 0;
+    }
+    const specDict = yaml.load(spec);
     if (!specDict) {
       return void 0;
     }
@@ -128,7 +122,8 @@ let APIHubToolset = class extends import_base_toolset.BaseToolset {
     return new import_openapi_toolset.OpenAPIToolset({
       specDict,
       authScheme: this.authScheme,
-      authCredential: this.authCredential
+      authCredential: this.authCredential,
+      toolFilter: this.toolFilter
     });
   }
 };