@google/adk 2.4.0 → 2.5.0

package/dist/esm/telemetry/api/internal/metrics/agent.js

@@ -0,0 +1,107 @@
+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
+ */
+import { ERROR_TYPE_ATTR, GenAiAttr } from "../common/attributes.js";
+import {
+  isExperimentalFeatureEnabled
+} from "../common/config.js";
+import {
+  cachedInstruments,
+  CALL_COUNT_BUCKETS,
+  createHistogram,
+  createTokenHistograms,
+  recordTokenHistograms
+} from "./meters.js";
+const PER_INVOCATION = "one agent invocation";
+const AGENT_DURATION_BUCKETS = Object.freeze([
+  0.1,
+  0.2,
+  0.4,
+  0.8,
+  1.6,
+  3.2,
+  6.4,
+  12.8,
+  25.6,
+  51.2,
+  102.4,
+  204.8,
+  409.6
+]);
+const getAgentInstruments = cachedInstruments((meter) => ({
+  duration: createHistogram({
+    meter,
+    name: "gen_ai.invoke_agent.duration",
+    unit: "s",
+    description: "Duration of agent invocations.",
+    buckets: AGENT_DURATION_BUCKETS
+  }),
+  inferenceCalls: createHistogram({
+    meter,
+    name: "gen_ai.invoke_agent.inference_calls",
+    unit: "1",
+    description: "Number of inference (model) calls per agent invocation.",
+    buckets: CALL_COUNT_BUCKETS
+  }),
+  toolCalls: createHistogram({
+    meter,
+    name: "gen_ai.invoke_agent.tool_calls",
+    unit: "1",
+    description: "Number of tool calls per agent invocation.",
+    buckets: CALL_COUNT_BUCKETS
+  }),
+  skillLoads: createHistogram({
+    meter,
+    name: "adk.experimental.invoke_agent.skill.loads",
+    unit: "1",
+    description: `Number of skill loads over ${PER_INVOCATION}.`,
+    buckets: CALL_COUNT_BUCKETS
+  }),
+  tokens: createTokenHistograms(
+    meter,
+    "adk.experimental.invoke_agent",
+    PER_INVOCATION
+  )
+}));
+function recordAgentDuration({
+  agentName,
+  durationSeconds,
+  errorType
+}) {
+  const attributes = {
+    [GenAiAttr.AGENT_NAME]: agentName,
+    ...errorType === void 0 ? {} : { [ERROR_TYPE_ATTR]: errorType }
+  };
+  getAgentInstruments().duration.record(durationSeconds, attributes);
+}
+__name(recordAgentDuration, "recordAgentDuration");
+function recordAgentTotals({
+  agentName,
+  totals,
+  config
+}) {
+  const instruments = getAgentInstruments();
+  const attributes = {
+    [GenAiAttr.AGENT_NAME]: agentName
+  };
+  if (totals.tokens !== void 0 && isExperimentalFeatureEnabled(config, "token_usage")) {
+    recordTokenHistograms(instruments.tokens, totals.tokens, attributes);
+  }
+  instruments.inferenceCalls.record(totals.inferenceCalls, attributes);
+  instruments.toolCalls.record(totals.toolCalls, attributes);
+  if (isExperimentalFeatureEnabled(config, "skills")) {
+    instruments.skillLoads.record(totals.skillLoads, attributes);
+  }
+}
+__name(recordAgentTotals, "recordAgentTotals");
+export {
+  AGENT_DURATION_BUCKETS,
+  recordAgentDuration,
+  recordAgentTotals
+};

package/dist/esm/telemetry/api/internal/metrics/inference_start_hook.js

@@ -0,0 +1,29 @@
+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
+ */
+import { formatError } from "../../../../utils/error_utils.js";
+import { logger } from "../../../../utils/logger.js";
+const INFERENCE_START_HOOK_KEY = /* @__PURE__ */ Symbol.for(
+  "google.adk.telemetry.inferenceStartHook"
+);
+function notifyInferenceStart() {
+  const hook = Reflect.get(globalThis, INFERENCE_START_HOOK_KEY);
+  if (typeof hook !== "function") {
+    return;
+  }
+  try {
+    hook();
+  } catch (error) {
+    logger.warn(`Model-call metric hook failed: ${formatError(error)}`);
+  }
+}
+__name(notifyInferenceStart, "notifyInferenceStart");
+export {
+  notifyInferenceStart
+};

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

@@ -0,0 +1,165 @@
+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
+ */
+import {
+  metrics
+} from "@opentelemetry/api";
+import { version } from "../../../../version.js";
+import { GEN_AI_SYSTEM_VALUE, SCHEMA_URL } from "../common/attributes.js";
+import {
+  CACHE_READ_INPUT_TOKENS_MEANING,
+  INPUT_TOKENS_MEANING,
+  OUTPUT_TOKENS_MEANING,
+  REASONING_OUTPUT_TOKENS_MEANING,
+  TOOL_INPUT_TOKENS_MEANING,
+  TOTAL_TOKENS_MEANING
+} from "../common/token_usage.js";
+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 = metrics.getMeterProvider();
+    let instruments = cache.get(provider);
+    if (instruments === void 0) {
+      instruments = create(
+        provider.getMeter(GEN_AI_SYSTEM_VALUE, version, {
+          schemaUrl: 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",
+      INPUT_TOKENS_MEANING,
+      INPUT_TOKEN_BUCKETS
+    ),
+    output: tokenHistogram(
+      "output_tokens",
+      OUTPUT_TOKENS_MEANING,
+      OUTPUT_TOKEN_BUCKETS
+    ),
+    total: tokenHistogram(
+      "total_tokens",
+      TOTAL_TOKENS_MEANING,
+      INPUT_TOKEN_BUCKETS
+    ),
+    cacheRead: tokenHistogram(
+      "cache_read.input_tokens",
+      CACHE_READ_INPUT_TOKENS_MEANING,
+      INPUT_TOKEN_BUCKETS
+    ),
+    reasoning: tokenHistogram(
+      "reasoning.output_tokens",
+      REASONING_OUTPUT_TOKENS_MEANING,
+      OUTPUT_TOKEN_BUCKETS
+    ),
+    toolInput: tokenHistogram(
+      "tool.input_tokens",
+      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");
+export {
+  CALL_COUNT_BUCKETS,
+  INPUT_TOKEN_BUCKETS,
+  OUTPUT_TOKEN_BUCKETS,
+  cachedInstruments,
+  createHistogram,
+  createTokenHistograms,
+  recordTokenHistograms
+};

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

@@ -0,0 +1,119 @@
+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
+ */
+import { ERROR_TYPE_ATTR, GenAiAttr } from "../common/attributes.js";
+import {
+  isExperimentalFeatureEnabled
+} from "../common/config.js";
+import { cachedInstruments, createHistogram } from "./meters.js";
+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 = cachedInstruments((meter) => ({
+  duration: 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 = {
+    [GenAiAttr.AGENT_NAME]: agentName,
+    [GenAiAttr.TOOL_NAME]: toolName,
+    [GenAiAttr.TOOL_TYPE]: toolType,
+    ...errorType === void 0 ? {} : { [ERROR_TYPE_ATTR]: errorType }
+  };
+  getToolInstruments().duration.record(durationSeconds, attributes);
+}
+__name(recordToolDuration, "recordToolDuration");
+function recordSkillLoad({
+  agentName,
+  skill,
+  errorType,
+  config
+}) {
+  var _a;
+  if (!isExperimentalFeatureEnabled(config, "skills")) {
+    return;
+  }
+  const attributes = {
+    [GenAiAttr.AGENT_NAME]: agentName,
+    [GenAiAttr.SKILL_NAME]: (_a = skill == null ? void 0 : skill.frontmatter.name) != null ? _a : HALLUCINATED,
+    ...errorType === void 0 ? {} : { [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 (!isExperimentalFeatureEnabled(config, "skills")) {
+    return;
+  }
+  const attributes = {
+    [GenAiAttr.AGENT_NAME]: agentName,
+    [GenAiAttr.SKILL_NAME]: (_a = skill == null ? void 0 : skill.frontmatter.name) != null ? _a : HALLUCINATED,
+    [GenAiAttr.SKILL_RESOURCE_NAME]: hasSkillScript(skill, scriptPath) ? scriptPath : HALLUCINATED
+  };
+  getToolInstruments().skillScriptExecutions.add(1, attributes);
+}
+__name(recordSkillScriptExecution, "recordSkillScriptExecution");
+export {
+  TOOL_DURATION_BUCKETS,
+  recordSkillLoad,
+  recordSkillScriptExecution,
+  recordToolDuration
+};

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

@@ -0,0 +1,112 @@
+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
+ */
+import { AdkAttr, ERROR_TYPE_ATTR, GenAiAttr } from "../common/attributes.js";
+import {
+  isExperimentalFeatureEnabled
+} from "../common/config.js";
+import {
+  cachedInstruments,
+  CALL_COUNT_BUCKETS,
+  createHistogram,
+  createTokenHistograms,
+  recordTokenHistograms
+} from "./meters.js";
+const PER_WORKFLOW = "one workflow invocation, across every agent that ran in it";
+const getWorkflowInstruments = cachedInstruments(
+  (meter) => ({
+    duration: createHistogram({
+      meter,
+      name: "gen_ai.invoke_workflow.duration",
+      unit: "s",
+      description: "Duration of workflow invocations."
+    }),
+    inferenceCalls: createHistogram({
+      meter,
+      name: "adk.experimental.invoke_workflow.inference_calls",
+      unit: "1",
+      description: `Number of inference (model) calls over ${PER_WORKFLOW}.`,
+      buckets: CALL_COUNT_BUCKETS
+    }),
+    toolCalls: 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: CALL_COUNT_BUCKETS
+    }),
+    skillLoads: createHistogram({
+      meter,
+      name: "adk.experimental.invoke_workflow.skill.loads",
+      unit: "1",
+      description: `Number of skill loads over ${PER_WORKFLOW}.`,
+      buckets: CALL_COUNT_BUCKETS
+    }),
+    compactions: 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: CALL_COUNT_BUCKETS
+    }),
+    tokens: createTokenHistograms(
+      meter,
+      "adk.experimental.invoke_workflow",
+      PER_WORKFLOW
+    )
+  })
+);
+function recordWorkflowDuration({
+  workflowName,
+  durationSeconds,
+  nested,
+  errorType
+}) {
+  const attributes = {
+    [GenAiAttr.OPERATION_NAME]: "invoke_workflow",
+    ...nested ? { [GenAiAttr.WORKFLOW_NESTED]: true } : {},
+    ...errorType === void 0 ? {} : { [ERROR_TYPE_ATTR]: errorType },
+    ...workflowName ? { [GenAiAttr.WORKFLOW_NAME]: workflowName } : {}
+  };
+  getWorkflowInstruments().duration.record(durationSeconds, attributes);
+}
+__name(recordWorkflowDuration, "recordWorkflowDuration");
+function recordWorkflowTotals({
+  rootAgentName,
+  workflowName,
+  nested,
+  totals,
+  config
+}) {
+  if (!isExperimentalFeatureEnabled(config, "workflow")) {
+    return;
+  }
+  const instruments = getWorkflowInstruments();
+  const attributes = {
+    [AdkAttr.EXPERIMENTAL_ROOT_AGENT_NAME]: rootAgentName,
+    ...workflowName ? { [GenAiAttr.WORKFLOW_NAME]: workflowName } : {},
+    ...nested ? { [GenAiAttr.WORKFLOW_NESTED]: true } : {}
+  };
+  if (totals.tokens !== void 0 && isExperimentalFeatureEnabled(config, "token_usage")) {
+    recordTokenHistograms(instruments.tokens, totals.tokens, attributes);
+  }
+  instruments.inferenceCalls.record(totals.inferenceCalls, attributes);
+  instruments.toolCalls.record(totals.toolCalls, attributes);
+  if (isExperimentalFeatureEnabled(config, "skills")) {
+    instruments.skillLoads.record(totals.skillLoads, attributes);
+  }
+  if (isExperimentalFeatureEnabled(config, "compaction")) {
+    instruments.compactions.record(totals.compactions, attributes);
+  }
+}
+__name(recordWorkflowTotals, "recordWorkflowTotals");
+export {
+  recordWorkflowDuration,
+  recordWorkflowTotals
+};

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

@@ -0,0 +1,25 @@
+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
+ */
+import { GenAiAttr } from "../common/attributes.js";
+function buildAgentInvocationAttributes({
+  agent,
+  sessionId
+}) {
+  return {
+    [GenAiAttr.OPERATION_NAME]: "invoke_agent",
+    [GenAiAttr.AGENT_DESCRIPTION]: agent.description,
+    [GenAiAttr.AGENT_NAME]: agent.name,
+    ...sessionId === void 0 ? {} : { [GenAiAttr.CONVERSATION_ID]: sessionId }
+  };
+}
+__name(buildAgentInvocationAttributes, "buildAgentInvocationAttributes");
+export {
+  buildAgentInvocationAttributes
+};

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

@@ -0,0 +1,50 @@
+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
+ */
+import { isCompactedEvent } from "../../../../events/compacted_event.js";
+import { toSnakeCaseName } from "../../../../utils/case_utils.js";
+import { GenAiAttr } from "../common/attributes.js";
+import { guessGeminiSystemName } from "../common/provider_name.js";
+import { getTracer } from "./tracer.js";
+function startCompactionSpan({
+  sessionId,
+  trigger
+}) {
+  const triggerName = toSnakeCaseName(trigger);
+  return getTracer().startSpan(`compact_events ${triggerName}`, {
+    attributes: {
+      [GenAiAttr.SYSTEM]: guessGeminiSystemName(),
+      [GenAiAttr.OPERATION_NAME]: "compact_events",
+      [GenAiAttr.CONVERSATION_ID]: sessionId,
+      [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(isCompactedEvent);
+  if (!compactedEvent) {
+    return {};
+  }
+  const { startTime, endTime } = compactedEvent;
+  return {
+    [GenAiAttr.COMPACTION_EVENT_COUNT]: eventsBefore.filter(
+      (event) => event.timestamp >= startTime && event.timestamp <= endTime
+    ).length,
+    [GenAiAttr.COMPACTION_RESULT_EVENT_ID]: compactedEvent.id,
+    [GenAiAttr.COMPACTION_START_TIMESTAMP]: startTime,
+    [GenAiAttr.COMPACTION_END_TIMESTAMP]: endTime
+  };
+}
+__name(buildCompactionResultAttributes, "buildCompactionResultAttributes");
+export {
+  buildCompactionResultAttributes,
+  startCompactionSpan
+};