@google/adk 2.4.0 → 2.5.0

package/dist/esm/telemetry/api/internal/trace/inference.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 { AdkAttr, GenAiAttr } from "../common/attributes.js";
+import {
+  isExperimentalFeatureEnabled,
+  shouldAddContentToSpans
+} from "../common/config.js";
+import { isReportedFinishReason } from "../common/finish_reason.js";
+import {
+  withoutContent
+} from "../common/genai_messages.js";
+import { safeJsonSerialize } from "../common/serialization.js";
+import { TokenUsage } from "../common/token_usage.js";
+import { getTracer } from "./tracer.js";
+function startInferenceSpan({
+  llmRequest,
+  commonAttributes
+}) {
+  var _a, _b;
+  const config = llmRequest.config;
+  return getTracer().startSpan(
+    `generate_content ${(_a = llmRequest.model) != null ? _a : ""}`.trim(),
+    {
+      attributes: {
+        [GenAiAttr.OPERATION_NAME]: "generate_content",
+        [GenAiAttr.REQUEST_MODEL]: (_b = llmRequest.model) != null ? _b : "",
+        ...(config == null ? void 0 : config.topP) === void 0 ? {} : { [GenAiAttr.REQUEST_TOP_P]: config.topP },
+        ...(config == null ? void 0 : config.maxOutputTokens) === void 0 ? {} : { [GenAiAttr.REQUEST_MAX_TOKENS]: config.maxOutputTokens },
+        ...commonAttributes
+      }
+    }
+  );
+}
+__name(startInferenceSpan, "startInferenceSpan");
+function buildResponseAttributes(llmResponse) {
+  return {
+    ...isReportedFinishReason(llmResponse.finishReason) ? {
+      [GenAiAttr.RESPONSE_FINISH_REASONS]: [
+        String(llmResponse.finishReason).toLowerCase()
+      ]
+    } : {},
+    ...llmResponse.usageMetadata ? new TokenUsage(llmResponse.usageMetadata).asAttributes() : {}
+  };
+}
+__name(buildResponseAttributes, "buildResponseAttributes");
+function groundingSourceUris(chunks) {
+  var _a, _b, _c;
+  const uris = /* @__PURE__ */ new Set();
+  for (const chunk of chunks) {
+    for (const uri of [
+      (_a = chunk.web) == null ? void 0 : _a.uri,
+      (_b = chunk.retrievedContext) == null ? void 0 : _b.uri,
+      (_c = chunk.maps) == null ? void 0 : _c.uri
+    ]) {
+      if (uri) {
+        uris.add(uri);
+      }
+    }
+  }
+  return [...uris];
+}
+__name(groundingSourceUris, "groundingSourceUris");
+function buildGroundingAttributes(groundingMetadata, captureContent) {
+  var _a, _b;
+  const queries = ((_a = groundingMetadata.webSearchQueries) != null ? _a : []).filter(Boolean);
+  const chunks = (_b = groundingMetadata.groundingChunks) != null ? _b : [];
+  const sourceUris = groundingSourceUris(chunks);
+  return {
+    [AdkAttr.EXPERIMENTAL_GROUNDING_QUERY_COUNT]: new Set(queries).size,
+    [AdkAttr.EXPERIMENTAL_GROUNDING_CHUNK_COUNT]: chunks.length,
+    ...captureContent && queries.length > 0 ? { [AdkAttr.EXPERIMENTAL_GROUNDING_WEB_SEARCH_QUERIES]: queries } : {},
+    ...captureContent && sourceUris.length > 0 ? { [AdkAttr.EXPERIMENTAL_GROUNDING_SOURCE_URIS]: sourceUris } : {}
+  };
+}
+__name(buildGroundingAttributes, "buildGroundingAttributes");
+function setInferenceResponseAttributes(span, llmResponse, config) {
+  span.setAttributes(buildResponseAttributes(llmResponse));
+  if (llmResponse.groundingMetadata && isExperimentalFeatureEnabled(config, "grounding")) {
+    span.setAttributes(
+      buildGroundingAttributes(
+        llmResponse.groundingMetadata,
+        shouldAddContentToSpans(config)
+      )
+    );
+  }
+}
+__name(setInferenceResponseAttributes, "setInferenceResponseAttributes");
+function setInferenceOperationDetails(span, details, config) {
+  const recorded = shouldAddContentToSpans(config) ? details : withoutContent(details);
+  for (const [key, value] of Object.entries(recorded)) {
+    span.setAttribute(key, safeJsonSerialize(value));
+  }
+}
+__name(setInferenceOperationDetails, "setInferenceOperationDetails");
+export {
+  buildResponseAttributes,
+  setInferenceOperationDetails,
+  setInferenceResponseAttributes,
+  startInferenceSpan
+};

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

@@ -0,0 +1,28 @@
+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 { GcpAttr } from "../common/attributes.js";
+import {
+  safeJsonSerialize,
+  shouldAddRequestResponseToSpans
+} from "../common/serialization.js";
+function setSendDataAttributes(span, { invocationContext, eventId, data }) {
+  span.setAttributes({
+    [GcpAttr.INVOCATION_ID]: invocationContext.invocationId,
+    [GcpAttr.EVENT_ID]: eventId
+  });
+  span.setAttribute(
+    GcpAttr.DATA,
+    shouldAddRequestResponseToSpans() ? safeJsonSerialize(data) : "{}"
+  );
+}
+__name(setSendDataAttributes, "setSendDataAttributes");
+export {
+  setSendDataAttributes
+};

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

@@ -0,0 +1,44 @@
+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 { GcpAttr, GenAiAttr } from "../common/attributes.js";
+import { getTracer } from "./tracer.js";
+const SELF_TRACED_NODE_BRANDS = [
+  /* @__PURE__ */ Symbol.for("google.adk.baseAgent"),
+  /* @__PURE__ */ Symbol.for("google.adk.workflow.workflow")
+];
+function hasOwnInvocationSpan(node) {
+  return SELF_TRACED_NODE_BRANDS.some(
+    (brand) => brand in node && Reflect.get(node, brand) === true
+  );
+}
+__name(hasOwnInvocationSpan, "hasOwnInvocationSpan");
+function startNodeSpan({
+  nodeName,
+  sessionId
+}) {
+  return getTracer().startSpan(`invoke_node ${nodeName}`, {
+    attributes: {
+      [GenAiAttr.OPERATION_NAME]: "invoke_node",
+      [GenAiAttr.CONVERSATION_ID]: sessionId
+    }
+  });
+}
+__name(startNodeSpan, "startNodeSpan");
+function setAssociatedEventIds(span, eventIds) {
+  if (eventIds.length > 0) {
+    span.setAttribute(GcpAttr.ASSOCIATED_EVENT_IDS, [...eventIds]);
+  }
+}
+__name(setAssociatedEventIds, "setAssociatedEventIds");
+export {
+  hasOwnInvocationSpan,
+  setAssociatedEventIds,
+  startNodeSpan
+};

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

@@ -0,0 +1,39 @@
+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
+ */
+const INCOMING_HEADERS_GETTER = Object.freeze({
+  keys: /* @__PURE__ */ __name((carrier) => Object.keys(carrier), "keys"),
+  get(carrier, key) {
+    const name = key.toLowerCase();
+    for (const [headerName, value] of Object.entries(carrier)) {
+      if (headerName.toLowerCase() === name) {
+        return value;
+      }
+    }
+    return void 0;
+  }
+});
+function addMissingHeaders(input, init, injected) {
+  var _a;
+  const isRequest = typeof Request !== "undefined" && input instanceof Request;
+  const headers = new Headers(
+    (_a = init == null ? void 0 : init.headers) != null ? _a : isRequest ? input.headers : void 0
+  );
+  for (const [name, value] of Object.entries(injected)) {
+    if (!headers.has(name)) {
+      headers.set(name, value);
+    }
+  }
+  return headers;
+}
+__name(addMissingHeaders, "addMissingHeaders");
+export {
+  INCOMING_HEADERS_GETTER,
+  addMissingHeaders
+};

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

@@ -0,0 +1,96 @@
+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,
+  GcpAttr,
+  GenAiAttr
+} from "../common/attributes.js";
+import { shouldAddContentToSpans } from "../common/config.js";
+import { redactCredentialSecrets } from "../common/redaction.js";
+import { safeJsonSerialize } from "../common/serialization.js";
+const UNSPECIFIED = "<not specified>";
+function serializeToolResult(result) {
+  try {
+    return safeJsonSerialize(redactCredentialSecrets(result));
+  } catch {
+    return "<not serializable>";
+  }
+}
+__name(serializeToolResult, "serializeToolResult");
+function buildToolCallAttributes({
+  tool,
+  args,
+  agentName,
+  outcome,
+  config
+}) {
+  var _a, _b, _c, _d;
+  const functionResponseEvent = outcome.kind === "response" ? outcome.functionResponseEvent : void 0;
+  const functionResponse = (_c = (_b = (_a = functionResponseEvent == null ? void 0 : functionResponseEvent.content) == null ? void 0 : _a.parts) == null ? void 0 : _b[0]) == null ? void 0 : _c.functionResponse;
+  const errorType = outcome.errorType;
+  const captureContent = shouldAddContentToSpans(config);
+  const result = functionResponse == null ? void 0 : functionResponse.response;
+  return {
+    [GenAiAttr.OPERATION_NAME]: "execute_tool",
+    [GenAiAttr.TOOL_DESCRIPTION]: tool.description,
+    [GenAiAttr.TOOL_NAME]: tool.name,
+    [GenAiAttr.TOOL_TYPE]: tool.constructor.name,
+    ...agentName ? { [GenAiAttr.AGENT_NAME]: agentName } : {},
+    ...errorType === void 0 ? {} : { [ERROR_TYPE_ATTR]: errorType },
+    [GenAiAttr.TOOL_CALL_ID]: (_d = functionResponse == null ? void 0 : functionResponse.id) != null ? _d : UNSPECIFIED,
+    ...functionResponseEvent ? { [GcpAttr.EVENT_ID]: functionResponseEvent.id } : {},
+    ...captureContent ? { [GenAiAttr.TOOL_CALL_ARGUMENTS]: safeJsonSerialize(args) } : {},
+    ...captureContent && result !== void 0 && result !== null ? { [GenAiAttr.TOOL_CALL_RESULT]: serializeToolResult(result) } : {}
+  };
+}
+__name(buildToolCallAttributes, "buildToolCallAttributes");
+function buildMergedToolCallsAttributes(responseEventId) {
+  return {
+    [GenAiAttr.OPERATION_NAME]: "execute_tool",
+    [GenAiAttr.TOOL_NAME]: "(merged tools)",
+    [GenAiAttr.TOOL_DESCRIPTION]: "(merged tools)",
+    [GenAiAttr.TOOL_CALL_ID]: responseEventId,
+    [GcpAttr.EVENT_ID]: responseEventId
+  };
+}
+__name(buildMergedToolCallsAttributes, "buildMergedToolCallsAttributes");
+function buildSkillSpanName(toolName, report) {
+  return report.resourceName === void 0 ? `execute_tool ${toolName} ${report.skillName}` : `execute_tool ${toolName} ${report.skillName} ${report.resourceName}`;
+}
+__name(buildSkillSpanName, "buildSkillSpanName");
+function buildSkillAttributes(report) {
+  var _a;
+  const { skill } = report;
+  const additionalTools = (_a = skill == null ? void 0 : skill.frontmatter.metadata) == null ? void 0 : _a["adk_additional_tools"];
+  return {
+    [GenAiAttr.SKILL_NAME]: report.skillName,
+    ...skill ? { [GenAiAttr.SKILL_DESCRIPTION]: skill.frontmatter.description } : {},
+    ...report.resourceName === void 0 ? {} : { [GenAiAttr.SKILL_RESOURCE_NAME]: report.resourceName },
+    ...report.isSkillLoad && skill && Array.isArray(additionalTools) ? {
+      [AdkAttr.SKILL_ADDITIONAL_TOOLS]: additionalTools.filter(
+        (name) => typeof name === "string"
+      )
+    } : {}
+  };
+}
+__name(buildSkillAttributes, "buildSkillAttributes");
+function setSkillSpanAttributes(span, toolName, report) {
+  span.updateName(buildSkillSpanName(toolName, report));
+  span.setAttributes(buildSkillAttributes(report));
+}
+__name(setSkillSpanAttributes, "setSkillSpanAttributes");
+export {
+  buildMergedToolCallsAttributes,
+  buildSkillAttributes,
+  buildSkillSpanName,
+  buildToolCallAttributes,
+  setSkillSpanAttributes
+};

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

@@ -0,0 +1,52 @@
+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 {
+  context,
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+import { version } from "../../../../version.js";
+import { GEN_AI_SYSTEM_VALUE, SCHEMA_URL } from "../common/attributes.js";
+import { resolveErrorType } from "../common/error.js";
+function getTracer() {
+  return trace.getTracerProvider().getTracer(GEN_AI_SYSTEM_VALUE, version, { schemaUrl: SCHEMA_URL });
+}
+__name(getTracer, "getTracer");
+function bindOtelContextToAsyncGenerator(ctx, generator) {
+  return {
+    next: context.bind(ctx, generator.next.bind(generator)),
+    return: context.bind(ctx, generator.return.bind(generator)),
+    throw: context.bind(ctx, generator.throw.bind(generator)),
+    [Symbol.asyncIterator]() {
+      return bindOtelContextToAsyncGenerator(
+        ctx,
+        generator[Symbol.asyncIterator]()
+      );
+    }
+  };
+}
+__name(bindOtelContextToAsyncGenerator, "bindOtelContextToAsyncGenerator");
+function setSpanError(span, error) {
+  const errorType = resolveErrorType(error);
+  let exception;
+  try {
+    exception = error instanceof Error ? error : errorType;
+  } catch {
+    exception = errorType;
+  }
+  span.recordException(exception);
+  span.setStatus({ code: SpanStatusCode.ERROR, message: errorType });
+}
+__name(setSpanError, "setSpanError");
+export {
+  bindOtelContextToAsyncGenerator,
+  getTracer,
+  setSpanError
+};

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

@@ -0,0 +1,54 @@
+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 {
+  context,
+  createContextKey,
+  trace
+} from "@opentelemetry/api";
+import { GenAiAttr, SUPPORT_ID_ATTR } from "../common/attributes.js";
+import { getTracer } from "./tracer.js";
+const SUPPORT_ID_KEY = createContextKey("google.adk.agent_engine.support_id");
+function getSupportId(parentContext, nested) {
+  if (nested) {
+    return void 0;
+  }
+  const parentSpanContext = trace.getSpanContext(parentContext);
+  if (parentSpanContext && !parentSpanContext.isRemote) {
+    return void 0;
+  }
+  const supportId = parentContext.getValue(SUPPORT_ID_KEY);
+  return typeof supportId === "string" ? supportId : void 0;
+}
+__name(getSupportId, "getSupportId");
+function startWorkflowSpan({
+  workflowName,
+  sessionId,
+  nested,
+  parentContext = context.active()
+}) {
+  const supportId = getSupportId(parentContext, nested);
+  return getTracer().startSpan(
+    workflowName ? `invoke_workflow ${workflowName}` : "invoke_workflow",
+    {
+      attributes: {
+        [GenAiAttr.OPERATION_NAME]: "invoke_workflow",
+        [GenAiAttr.CONVERSATION_ID]: sessionId,
+        ...nested ? { [GenAiAttr.WORKFLOW_NESTED]: true } : {},
+        ...workflowName ? { [GenAiAttr.WORKFLOW_NAME]: workflowName } : {},
+        ...supportId ? { [SUPPORT_ID_ATTR]: supportId } : {}
+      }
+    },
+    parentContext
+  );
+}
+__name(startWorkflowSpan, "startWorkflowSpan");
+export {
+  startWorkflowSpan
+};

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

@@ -0,0 +1,67 @@
+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 {
+  context,
+  createContextKey,
+  trace
+} from "@opentelemetry/api";
+const AGENT_ENGINE_TRACEPARENT_HEADER = "google-agent-engine-traceparent";
+const TRACEPARENT_HEADER = "traceparent";
+const MAX_SUPPORT_ID_LENGTH = 256;
+const SUPPORT_ID_KEY = createContextKey("google.adk.agent_engine.support_id");
+const TRACEPARENT_PATTERN = /^\s?([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(-.*)?\s?$/;
+function parseTraceparent(value) {
+  const match = TRACEPARENT_PATTERN.exec(value);
+  if (!match) {
+    return void 0;
+  }
+  const [, version, traceId, spanId, flags, rest] = match;
+  if (version === "ff" || version === "00" && rest) {
+    return void 0;
+  }
+  const spanContext = {
+    traceId,
+    spanId,
+    traceFlags: parseInt(flags, 16),
+    isRemote: true
+  };
+  return trace.isSpanContextValid(spanContext) ? spanContext : void 0;
+}
+__name(parseTraceparent, "parseTraceparent");
+function getHeader(headers, name) {
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name) {
+      return Array.isArray(value) ? value[0] : value;
+    }
+  }
+  return void 0;
+}
+__name(getHeader, "getHeader");
+function runWithAgentEngineContext(headers, fn) {
+  var _a;
+  let ctx = context.active();
+  const agentEngineTraceparent = getHeader(
+    headers,
+    AGENT_ENGINE_TRACEPARENT_HEADER
+  );
+  const remoteParent = agentEngineTraceparent === void 0 ? void 0 : parseTraceparent(agentEngineTraceparent);
+  if (remoteParent && !trace.getSpan(ctx)) {
+    ctx = trace.setSpanContext(ctx, remoteParent);
+  }
+  const supportId = (_a = getHeader(headers, TRACEPARENT_HEADER)) == null ? void 0 : _a.trim();
+  if (supportId && supportId.length <= MAX_SUPPORT_ID_LENGTH) {
+    ctx = ctx.setValue(SUPPORT_ID_KEY, supportId);
+  }
+  return context.with(ctx, fn);
+}
+__name(runWithAgentEngineContext, "runWithAgentEngineContext");
+export {
+  runWithAgentEngineContext
+};

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

@@ -0,0 +1,46 @@
+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";
+import { isRequestDrivenMetricReader } from "./request_driven_metric_reader.js";
+function agentRuntimeRequestHooks(otelHooks) {
+  var _a, _b, _c;
+  const readers = ((_a = otelHooks.metricReaders) != null ? _a : []).filter(
+    isRequestDrivenMetricReader
+  );
+  const flushables = [
+    ...(_b = otelHooks.spanProcessors) != null ? _b : [],
+    ...(_c = otelHooks.logRecordProcessors) != null ? _c : []
+  ];
+  return {
+    onRequestStart() {
+      for (const reader of readers) {
+        reader.onRequestStart();
+      }
+    },
+    async onRequestEnd() {
+      const results = await Promise.allSettled([
+        ...readers.map(async (reader) => reader.onRequestEnd()),
+        ...flushables.map(async (processor) => processor.forceFlush())
+      ]);
+      for (const result of results) {
+        if (result.status === "rejected") {
+          logger.warn(
+            `Telemetry flush on request end failed: ${formatError(result.reason)}`
+          );
+        }
+      }
+    }
+  };
+}
+__name(agentRuntimeRequestHooks, "agentRuntimeRequestHooks");
+export {
+  agentRuntimeRequestHooks
+};