@google/adk 2.4.0 → 2.5.0

package/dist/cjs/telemetry/api/internal/metrics/meters.js

@@ -0,0 +1,189 @@
+/**
+  * @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 meters_exports = {};
+__export(meters_exports, {
+  CALL_COUNT_BUCKETS: () => CALL_COUNT_BUCKETS,
+  INPUT_TOKEN_BUCKETS: () => INPUT_TOKEN_BUCKETS,
+  OUTPUT_TOKEN_BUCKETS: () => OUTPUT_TOKEN_BUCKETS,
+  cachedInstruments: () => cachedInstruments,
+  createHistogram: () => createHistogram,
+  createTokenHistograms: () => createTokenHistograms,
+  recordTokenHistograms: () => recordTokenHistograms
+});
+module.exports = __toCommonJS(meters_exports);
+var import_api = require("@opentelemetry/api");
+var import_version = require("../../../../version.js");
+var import_attributes = require("../common/attributes.js");
+var import_token_usage = require("../common/token_usage.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const CALL_COUNT_BUCKETS = Object.freeze([
+  0,
+  1,
+  2,
+  3,
+  4,
+  5,
+  6,
+  8,
+  12,
+  16,
+  24,
+  32,
+  64,
+  128,
+  256,
+  512
+]);
+const INPUT_TOKEN_BUCKETS = Object.freeze([
+  0,
+  128,
+  256,
+  512,
+  1024,
+  2048,
+  4096,
+  8192,
+  16384,
+  32768,
+  65536,
+  131072,
+  262144,
+  524288,
+  1048576
+]);
+const OUTPUT_TOKEN_BUCKETS = Object.freeze([
+  0,
+  32,
+  64,
+  128,
+  256,
+  512,
+  1024,
+  2048,
+  4096,
+  8192,
+  16384,
+  32768,
+  65536,
+  131072
+]);
+function cachedInstruments(create) {
+  const cache = /* @__PURE__ */ new WeakMap();
+  return () => {
+    const provider = import_api.metrics.getMeterProvider();
+    let instruments = cache.get(provider);
+    if (instruments === void 0) {
+      instruments = create(
+        provider.getMeter(import_attributes.GEN_AI_SYSTEM_VALUE, import_version.version, {
+          schemaUrl: import_attributes.SCHEMA_URL
+        })
+      );
+      cache.set(provider, instruments);
+    }
+    return instruments;
+  };
+}
+__name(cachedInstruments, "cachedInstruments");
+function createHistogram({
+  meter,
+  name,
+  unit,
+  description,
+  buckets
+}) {
+  return meter.createHistogram(name, {
+    unit,
+    description,
+    ...buckets === void 0 ? {} : { advice: { explicitBucketBoundaries: [...buckets] } }
+  });
+}
+__name(createHistogram, "createHistogram");
+function createTokenHistograms(meter, prefix, scopeDescription) {
+  const tokenHistogram = /* @__PURE__ */ __name((suffix, meaning, buckets) => createHistogram({
+    meter,
+    name: `${prefix}.${suffix}`,
+    unit: "{token}",
+    description: `${meaning} Summed over ${scopeDescription}.`,
+    buckets
+  }), "tokenHistogram");
+  return {
+    input: tokenHistogram(
+      "input_tokens",
+      import_token_usage.INPUT_TOKENS_MEANING,
+      INPUT_TOKEN_BUCKETS
+    ),
+    output: tokenHistogram(
+      "output_tokens",
+      import_token_usage.OUTPUT_TOKENS_MEANING,
+      OUTPUT_TOKEN_BUCKETS
+    ),
+    total: tokenHistogram(
+      "total_tokens",
+      import_token_usage.TOTAL_TOKENS_MEANING,
+      INPUT_TOKEN_BUCKETS
+    ),
+    cacheRead: tokenHistogram(
+      "cache_read.input_tokens",
+      import_token_usage.CACHE_READ_INPUT_TOKENS_MEANING,
+      INPUT_TOKEN_BUCKETS
+    ),
+    reasoning: tokenHistogram(
+      "reasoning.output_tokens",
+      import_token_usage.REASONING_OUTPUT_TOKENS_MEANING,
+      OUTPUT_TOKEN_BUCKETS
+    ),
+    toolInput: tokenHistogram(
+      "tool.input_tokens",
+      import_token_usage.TOOL_INPUT_TOKENS_MEANING,
+      INPUT_TOKEN_BUCKETS
+    )
+  };
+}
+__name(createTokenHistograms, "createTokenHistograms");
+function recordTokenHistograms(histograms, usage, attributes) {
+  var _a, _b, _c, _d, _e;
+  histograms.input.record((_a = usage.input) != null ? _a : 0, attributes);
+  histograms.output.record((_b = usage.output) != null ? _b : 0, attributes);
+  histograms.total.record(usage.totalTokenUsage(), attributes);
+  histograms.cacheRead.record((_c = usage.cacheRead) != null ? _c : 0, attributes);
+  histograms.reasoning.record((_d = usage.reasoning) != null ? _d : 0, attributes);
+  histograms.toolInput.record((_e = usage.toolInput) != null ? _e : 0, attributes);
+}
+__name(recordTokenHistograms, "recordTokenHistograms");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CALL_COUNT_BUCKETS,
+  INPUT_TOKEN_BUCKETS,
+  OUTPUT_TOKEN_BUCKETS,
+  cachedInstruments,
+  createHistogram,
+  createTokenHistograms,
+  recordTokenHistograms
+});

package/dist/cjs/telemetry/api/internal/metrics/tool.js

@@ -0,0 +1,147 @@
+/**
+  * @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 tool_exports = {};
+__export(tool_exports, {
+  TOOL_DURATION_BUCKETS: () => TOOL_DURATION_BUCKETS,
+  recordSkillLoad: () => recordSkillLoad,
+  recordSkillScriptExecution: () => recordSkillScriptExecution,
+  recordToolDuration: () => recordToolDuration
+});
+module.exports = __toCommonJS(tool_exports);
+var import_attributes = require("../common/attributes.js");
+var import_config = require("../common/config.js");
+var import_meters = require("./meters.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const HALLUCINATED = "<hallucinated>";
+const TOOL_DURATION_BUCKETS = Object.freeze([
+  0.01,
+  0.02,
+  0.04,
+  0.08,
+  0.16,
+  0.32,
+  0.64,
+  1.28,
+  2.56,
+  5.12,
+  10.24,
+  20.48,
+  40.96,
+  81.92
+]);
+const getToolInstruments = (0, import_meters.cachedInstruments)((meter) => ({
+  duration: (0, import_meters.createHistogram)({
+    meter,
+    name: "gen_ai.execute_tool.duration",
+    unit: "s",
+    description: "Duration of tool executions.",
+    buckets: TOOL_DURATION_BUCKETS
+  }),
+  skillLoads: meter.createCounter("adk.experimental.skill.loads", {
+    unit: "1",
+    description: "Number of times a skill was loaded. Counts the attempt, so a load that resolved no skill is counted too, under its `error.type`."
+  }),
+  skillScriptExecutions: meter.createCounter(
+    "adk.experimental.skill.script.executions",
+    {
+      unit: "1",
+      description: "Number of skill script executions."
+    }
+  )
+}));
+function recordToolDuration({
+  agentName,
+  toolName,
+  toolType,
+  durationSeconds,
+  errorType
+}) {
+  const attributes = {
+    [import_attributes.GenAiAttr.AGENT_NAME]: agentName,
+    [import_attributes.GenAiAttr.TOOL_NAME]: toolName,
+    [import_attributes.GenAiAttr.TOOL_TYPE]: toolType,
+    ...errorType === void 0 ? {} : { [import_attributes.ERROR_TYPE_ATTR]: errorType }
+  };
+  getToolInstruments().duration.record(durationSeconds, attributes);
+}
+__name(recordToolDuration, "recordToolDuration");
+function recordSkillLoad({
+  agentName,
+  skill,
+  errorType,
+  config
+}) {
+  var _a;
+  if (!(0, import_config.isExperimentalFeatureEnabled)(config, "skills")) {
+    return;
+  }
+  const attributes = {
+    [import_attributes.GenAiAttr.AGENT_NAME]: agentName,
+    [import_attributes.GenAiAttr.SKILL_NAME]: (_a = skill == null ? void 0 : skill.frontmatter.name) != null ? _a : HALLUCINATED,
+    ...errorType === void 0 ? {} : { [import_attributes.ERROR_TYPE_ATTR]: errorType }
+  };
+  getToolInstruments().skillLoads.add(1, attributes);
+}
+__name(recordSkillLoad, "recordSkillLoad");
+function hasSkillScript(skill, scriptPath) {
+  var _a;
+  const scripts = (_a = skill == null ? void 0 : skill.resources) == null ? void 0 : _a.scripts;
+  if (!scripts) {
+    return false;
+  }
+  const relativePath = scriptPath.startsWith("scripts/") ? scriptPath.slice("scripts/".length) : scriptPath;
+  return Object.prototype.hasOwnProperty.call(scripts, relativePath) || Object.prototype.hasOwnProperty.call(scripts, scriptPath);
+}
+__name(hasSkillScript, "hasSkillScript");
+function recordSkillScriptExecution({
+  agentName,
+  skill,
+  scriptPath,
+  config
+}) {
+  var _a;
+  if (!(0, import_config.isExperimentalFeatureEnabled)(config, "skills")) {
+    return;
+  }
+  const attributes = {
+    [import_attributes.GenAiAttr.AGENT_NAME]: agentName,
+    [import_attributes.GenAiAttr.SKILL_NAME]: (_a = skill == null ? void 0 : skill.frontmatter.name) != null ? _a : HALLUCINATED,
+    [import_attributes.GenAiAttr.SKILL_RESOURCE_NAME]: hasSkillScript(skill, scriptPath) ? scriptPath : HALLUCINATED
+  };
+  getToolInstruments().skillScriptExecutions.add(1, attributes);
+}
+__name(recordSkillScriptExecution, "recordSkillScriptExecution");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TOOL_DURATION_BUCKETS,
+  recordSkillLoad,
+  recordSkillScriptExecution,
+  recordToolDuration
+});

package/dist/cjs/telemetry/api/internal/metrics/workflow.js

@@ -0,0 +1,132 @@
+/**
+  * @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 workflow_exports = {};
+__export(workflow_exports, {
+  recordWorkflowDuration: () => recordWorkflowDuration,
+  recordWorkflowTotals: () => recordWorkflowTotals
+});
+module.exports = __toCommonJS(workflow_exports);
+var import_attributes = require("../common/attributes.js");
+var import_config = require("../common/config.js");
+var import_meters = require("./meters.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const PER_WORKFLOW = "one workflow invocation, across every agent that ran in it";
+const getWorkflowInstruments = (0, import_meters.cachedInstruments)(
+  (meter) => ({
+    duration: (0, import_meters.createHistogram)({
+      meter,
+      name: "gen_ai.invoke_workflow.duration",
+      unit: "s",
+      description: "Duration of workflow invocations."
+    }),
+    inferenceCalls: (0, import_meters.createHistogram)({
+      meter,
+      name: "adk.experimental.invoke_workflow.inference_calls",
+      unit: "1",
+      description: `Number of inference (model) calls over ${PER_WORKFLOW}.`,
+      buckets: import_meters.CALL_COUNT_BUCKETS
+    }),
+    toolCalls: (0, import_meters.createHistogram)({
+      meter,
+      name: "adk.experimental.invoke_workflow.tool_calls",
+      unit: "1",
+      description: `Number of tool calls over ${PER_WORKFLOW}. Includes the \`transfer_to_agent\` calls that route between them.`,
+      buckets: import_meters.CALL_COUNT_BUCKETS
+    }),
+    skillLoads: (0, import_meters.createHistogram)({
+      meter,
+      name: "adk.experimental.invoke_workflow.skill.loads",
+      unit: "1",
+      description: `Number of skill loads over ${PER_WORKFLOW}.`,
+      buckets: import_meters.CALL_COUNT_BUCKETS
+    }),
+    compactions: (0, import_meters.createHistogram)({
+      meter,
+      name: "adk.experimental.invoke_workflow.compactions",
+      unit: "1",
+      description: `Number of conversation compactions over ${PER_WORKFLOW}. Counts every summary produced, including one the runner then discards because a newer turn changed the session meanwhile. Recorded whether or not the workflow compacted, so the share of turns that do is readable off the unnested datapoints.`,
+      buckets: import_meters.CALL_COUNT_BUCKETS
+    }),
+    tokens: (0, import_meters.createTokenHistograms)(
+      meter,
+      "adk.experimental.invoke_workflow",
+      PER_WORKFLOW
+    )
+  })
+);
+function recordWorkflowDuration({
+  workflowName,
+  durationSeconds,
+  nested,
+  errorType
+}) {
+  const attributes = {
+    [import_attributes.GenAiAttr.OPERATION_NAME]: "invoke_workflow",
+    ...nested ? { [import_attributes.GenAiAttr.WORKFLOW_NESTED]: true } : {},
+    ...errorType === void 0 ? {} : { [import_attributes.ERROR_TYPE_ATTR]: errorType },
+    ...workflowName ? { [import_attributes.GenAiAttr.WORKFLOW_NAME]: workflowName } : {}
+  };
+  getWorkflowInstruments().duration.record(durationSeconds, attributes);
+}
+__name(recordWorkflowDuration, "recordWorkflowDuration");
+function recordWorkflowTotals({
+  rootAgentName,
+  workflowName,
+  nested,
+  totals,
+  config
+}) {
+  if (!(0, import_config.isExperimentalFeatureEnabled)(config, "workflow")) {
+    return;
+  }
+  const instruments = getWorkflowInstruments();
+  const attributes = {
+    [import_attributes.AdkAttr.EXPERIMENTAL_ROOT_AGENT_NAME]: rootAgentName,
+    ...workflowName ? { [import_attributes.GenAiAttr.WORKFLOW_NAME]: workflowName } : {},
+    ...nested ? { [import_attributes.GenAiAttr.WORKFLOW_NESTED]: true } : {}
+  };
+  if (totals.tokens !== void 0 && (0, import_config.isExperimentalFeatureEnabled)(config, "token_usage")) {
+    (0, import_meters.recordTokenHistograms)(instruments.tokens, totals.tokens, attributes);
+  }
+  instruments.inferenceCalls.record(totals.inferenceCalls, attributes);
+  instruments.toolCalls.record(totals.toolCalls, attributes);
+  if ((0, import_config.isExperimentalFeatureEnabled)(config, "skills")) {
+    instruments.skillLoads.record(totals.skillLoads, attributes);
+  }
+  if ((0, import_config.isExperimentalFeatureEnabled)(config, "compaction")) {
+    instruments.compactions.record(totals.compactions, attributes);
+  }
+}
+__name(recordWorkflowTotals, "recordWorkflowTotals");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  recordWorkflowDuration,
+  recordWorkflowTotals
+});

package/dist/cjs/telemetry/api/internal/trace/agent.js

@@ -0,0 +1,52 @@
+/**
+  * @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 agent_exports = {};
+__export(agent_exports, {
+  buildAgentInvocationAttributes: () => buildAgentInvocationAttributes
+});
+module.exports = __toCommonJS(agent_exports);
+var import_attributes = require("../common/attributes.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function buildAgentInvocationAttributes({
+  agent,
+  sessionId
+}) {
+  return {
+    [import_attributes.GenAiAttr.OPERATION_NAME]: "invoke_agent",
+    [import_attributes.GenAiAttr.AGENT_DESCRIPTION]: agent.description,
+    [import_attributes.GenAiAttr.AGENT_NAME]: agent.name,
+    ...sessionId === void 0 ? {} : { [import_attributes.GenAiAttr.CONVERSATION_ID]: sessionId }
+  };
+}
+__name(buildAgentInvocationAttributes, "buildAgentInvocationAttributes");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildAgentInvocationAttributes
+});

package/dist/cjs/telemetry/api/internal/trace/compaction.js

@@ -0,0 +1,78 @@
+/**
+  * @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 compaction_exports = {};
+__export(compaction_exports, {
+  buildCompactionResultAttributes: () => buildCompactionResultAttributes,
+  startCompactionSpan: () => startCompactionSpan
+});
+module.exports = __toCommonJS(compaction_exports);
+var import_compacted_event = require("../../../../events/compacted_event.js");
+var import_case_utils = require("../../../../utils/case_utils.js");
+var import_attributes = require("../common/attributes.js");
+var import_provider_name = require("../common/provider_name.js");
+var import_tracer = require("./tracer.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function startCompactionSpan({
+  sessionId,
+  trigger
+}) {
+  const triggerName = (0, import_case_utils.toSnakeCaseName)(trigger);
+  return (0, import_tracer.getTracer)().startSpan(`compact_events ${triggerName}`, {
+    attributes: {
+      [import_attributes.GenAiAttr.SYSTEM]: (0, import_provider_name.guessGeminiSystemName)(),
+      [import_attributes.GenAiAttr.OPERATION_NAME]: "compact_events",
+      [import_attributes.GenAiAttr.CONVERSATION_ID]: sessionId,
+      [import_attributes.GenAiAttr.COMPACTION_TRIGGER]: triggerName
+    }
+  });
+}
+__name(startCompactionSpan, "startCompactionSpan");
+function buildCompactionResultAttributes(eventsBefore, eventsAfter) {
+  const before = new Set(eventsBefore);
+  const compactedEvent = eventsAfter.filter((event) => !before.has(event)).find(import_compacted_event.isCompactedEvent);
+  if (!compactedEvent) {
+    return {};
+  }
+  const { startTime, endTime } = compactedEvent;
+  return {
+    [import_attributes.GenAiAttr.COMPACTION_EVENT_COUNT]: eventsBefore.filter(
+      (event) => event.timestamp >= startTime && event.timestamp <= endTime
+    ).length,
+    [import_attributes.GenAiAttr.COMPACTION_RESULT_EVENT_ID]: compactedEvent.id,
+    [import_attributes.GenAiAttr.COMPACTION_START_TIMESTAMP]: startTime,
+    [import_attributes.GenAiAttr.COMPACTION_END_TIMESTAMP]: endTime
+  };
+}
+__name(buildCompactionResultAttributes, "buildCompactionResultAttributes");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildCompactionResultAttributes,
+  startCompactionSpan
+});