@google/adk 2.3.0 → 2.5.0

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

@@ -0,0 +1,276 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a, _b;
+import { context, createContextKey } from "@opentelemetry/api";
+import {
+  MetricReader
+} from "@opentelemetry/sdk-metrics";
+import { formatError } from "../../utils/error_utils.js";
+import { logger } from "../../utils/logger.js";
+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 = 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 = 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) {
+      logger.warn(`Metric request-start hook failed: ${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) {
+      logger.warn(`Metric request-end hook failed: ${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;
+          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) {
+      logger.warn(`Metric model-call hook failed: ${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) {
+        logger.warn(`Metric collection reported: ${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) {
+      logger.warn(`Request-driven metric export failed: ${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) => {
+      context.with(
+        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: ${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;
+  }
+  logger.warn(
+    `Found invalid value for ${name}=${JSON.stringify(raw)}, using default ${fallback}.`
+  );
+  return fallback;
+}
+__name(resolveMillis, "resolveMillis");
+export {
+  MIN_EXPORT_INTERVAL_MS,
+  RequestDrivenMetricReader,
+  isRequestDrivenMetricReader
+};

package/dist/esm/telemetry/export/setup.js

@@ -0,0 +1,160 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  createNoopMeter,
+  metrics,
+  ProxyTracerProvider,
+  trace
+} from "@opentelemetry/api";
+import { logs } from "@opentelemetry/api-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { detectResources, envDetector } from "@opentelemetry/resources";
+import {
+  BatchLogRecordProcessor,
+  LoggerProvider
+} from "@opentelemetry/sdk-logs";
+import {
+  MeterProvider,
+  PeriodicExportingMetricReader
+} from "@opentelemetry/sdk-metrics";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+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(exportersConfig)];
+  const spanProcessors = allHooks.flatMap(
+    (hooks) => hooks.spanProcessors || []
+  );
+  const metricReaders = allHooks.flatMap((hooks) => hooks.metricReaders || []);
+  const logRecordProcessors = allHooks.flatMap(
+    (hooks) => hooks.logRecordProcessors || []
+  );
+  if (!tracerAlreadySet && spanProcessors.length > 0) {
+    const tracerProvider = new NodeTracerProvider({
+      resource,
+      spanProcessors
+    });
+    tracerProvider.register();
+  }
+  if (!meterAlreadySet && metricReaders.length > 0) {
+    const meterProvider = new MeterProvider({
+      readers: metricReaders,
+      resource
+    });
+    metrics.setGlobalMeterProvider(meterProvider);
+  }
+  if (!loggerAlreadySet && logRecordProcessors.length > 0) {
+    const loggerProvider = new LoggerProvider({
+      resource,
+      processors: logRecordProcessors
+    });
+    logs.setGlobalLoggerProvider(loggerProvider);
+  }
+}
+__name(maybeSetOtelProviders, "maybeSetOtelProviders");
+function getOtelResource() {
+  return detectResources({
+    detectors: [envDetector]
+  });
+}
+__name(getOtelResource, "getOtelResource");
+function getOtelExportersConfig() {
+  return {
+    enableTracing: !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT),
+    enableMetrics: !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT),
+    enableLogging: !!(process.env.OTEL_EXPORTER_OTLP_ENDPOINT || process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT)
+  };
+}
+__name(getOtelExportersConfig, "getOtelExportersConfig");
+function getOtelExporters(config = getOtelExportersConfig()) {
+  const { enableTracing, enableMetrics, enableLogging } = config;
+  return {
+    spanProcessors: enableTracing ? [new BatchSpanProcessor(new OTLPTraceExporter())] : [],
+    metricReaders: enableMetrics ? [
+      new PeriodicExportingMetricReader({
+        exporter: new OTLPMetricExporter()
+      })
+    ] : [],
+    logRecordProcessors: enableLogging ? [new BatchLogRecordProcessor({ exporter: new OTLPLogExporter() })] : []
+  };
+}
+__name(getOtelExporters, "getOtelExporters");
+function isTracerProviderRegistered() {
+  var _a, _b, _c, _d, _e, _f, _g;
+  const provider = (_b = (_a = trace).getTracerProvider) == null ? void 0 : _b.call(_a);
+  if (!provider) {
+    return false;
+  }
+  const noopDelegate = typeof ProxyTracerProvider === "function" ? (_d = (_c = new 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 = metrics).getMeterProvider) == null ? void 0 : _b.call(_a);
+  if (!provider) {
+    return false;
+  }
+  const noopMeter = typeof createNoopMeter === "function" ? 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 = 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");
+export {
+  maybeSetOtelProviders
+};

package/dist/esm/tools/agent_tool.js

@@ -9,6 +9,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  */
 var _a, _b;
 import { Type } from "@google/genai";
+import { isEqual } from "lodash-es";
 import { isLlmAgent } from "../agents/llm_agent.js";
 import { InMemoryMemoryService } from "../memory/in_memory_memory_service.js";
 import { Runner } from "../runner/runner.js";
@@ -129,12 +130,18 @@ const _AgentTool = class _AgentTool extends (_b = BaseTool, _a = AGENT_TOOL_SIGN
       memoryService: (_b2 = toolContext.invocationContext.memoryService) != null ? _b2 : new 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(State.TEMP_PREFIX) && !isEqual(session.state[key], value)
+      )
+    );
     if ((_c = toolContext.abortSignal) == null ? void 0 : _c.aborted) {
       return "";
     }
@@ -143,6 +150,7 @@ const _AgentTool = class _AgentTool extends (_b = BaseTool, _a = AGENT_TOOL_SIGN
       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/esm/tools/apihub_tool/apihub_toolset.js

@@ -16,7 +16,7 @@ var __decorateClass = (decorators, target, key, kind) => {
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import yaml from "js-yaml";
+import * as yaml from "js-yaml";
 import { toSnakeCaseName } from "../../utils/case_utils.js";
 import { experimental } from "../../utils/experimental.js";
 import { BaseToolset } from "../base_toolset.js";
@@ -24,15 +24,15 @@ import { OpenAPIToolset } from "../openapi_tool/openapi_toolset.js";
 import { APIHubClient } from "./clients/apihub_client.js";
 let APIHubToolset = class extends 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 APIHubClient({
+    this.apihubClient = (_e = options.apihubClient) != null ? _e : new APIHubClient({
       accessToken: options.accessToken,
       serviceAccountJson: options.serviceAccountJson
     });
@@ -51,21 +51,12 @@ let APIHubToolset = class extends 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) {
@@ -84,6 +75,9 @@ let APIHubToolset = class extends BaseToolset {
     const spec = await this.apihubClient.getSpecContent(
       this.apihubResourceName
     );
+    if (!spec.trim()) {
+      return void 0;
+    }
     const specDict = yaml.load(spec);
     if (!specDict) {
       return void 0;
@@ -93,7 +87,8 @@ let APIHubToolset = class extends BaseToolset {
     return new OpenAPIToolset({
       specDict,
       authScheme: this.authScheme,
-      authCredential: this.authCredential
+      authCredential: this.authCredential,
+      toolFilter: this.toolFilter
     });
   }
 };