@google/adk 2.4.0 → 2.5.0

package/dist/types/telemetry/api/internal/common/attributes.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** OpenTelemetry GenAI semantic-convention attribute keys. */
+export declare enum GenAiAttr {
+    AGENT_DESCRIPTION = "gen_ai.agent.description",
+    AGENT_NAME = "gen_ai.agent.name",
+    CONVERSATION_ID = "gen_ai.conversation.id",
+    OPERATION_NAME = "gen_ai.operation.name",
+    PROVIDER_NAME = "gen_ai.provider.name",
+    SYSTEM = "gen_ai.system",
+    WORKFLOW_NAME = "gen_ai.workflow.name",
+    WORKFLOW_NESTED = "gen_ai.workflow.nested",
+    TOOL_CALL_ID = "gen_ai.tool.call.id",
+    TOOL_CALL_ARGUMENTS = "gen_ai.tool.call.arguments",
+    TOOL_CALL_RESULT = "gen_ai.tool.call.result",
+    TOOL_DEFINITIONS = "gen_ai.tool.definitions",
+    TOOL_DESCRIPTION = "gen_ai.tool.description",
+    TOOL_NAME = "gen_ai.tool.name",
+    TOOL_TYPE = "gen_ai.tool.type",
+    REQUEST_MODEL = "gen_ai.request.model",
+    REQUEST_TOP_P = "gen_ai.request.top_p",
+    REQUEST_MAX_TOKENS = "gen_ai.request.max_tokens",
+    RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons",
+    INPUT_MESSAGES = "gen_ai.input.messages",
+    OUTPUT_MESSAGES = "gen_ai.output.messages",
+    SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions",
+    USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens",
+    USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens",
+    USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens",
+    USAGE_REASONING_OUTPUT_TOKENS = "gen_ai.usage.reasoning.output_tokens",
+    SKILL_NAME = "gen_ai.skill.name",
+    SKILL_DESCRIPTION = "gen_ai.skill.description",
+    SKILL_RESOURCE_NAME = "gen_ai.skill.resource.name",
+    COMPACTION_TRIGGER = "gen_ai.compaction.trigger",
+    COMPACTION_EVENT_COUNT = "gen_ai.compaction.event_count",
+    COMPACTION_RESULT_EVENT_ID = "gen_ai.compaction.result_event_id",
+    COMPACTION_START_TIMESTAMP = "gen_ai.compaction.start_timestamp",
+    COMPACTION_END_TIMESTAMP = "gen_ai.compaction.end_timestamp"
+}
+/** ADK-specific attribute keys outside the GenAI semantic conventions. */
+export declare enum AdkAttr {
+    SKILL_ADDITIONAL_TOOLS = "adk.skill.additional_tools",
+    EXPERIMENTAL_ROOT_AGENT_NAME = "adk.experimental.root_agent.name",
+    EXPERIMENTAL_GROUNDING_QUERY_COUNT = "adk.experimental.grounding.query_count",
+    EXPERIMENTAL_GROUNDING_CHUNK_COUNT = "adk.experimental.grounding.chunk_count",
+    EXPERIMENTAL_GROUNDING_WEB_SEARCH_QUERIES = "adk.experimental.grounding.web_search_queries",
+    EXPERIMENTAL_GROUNDING_SOURCE_URIS = "adk.experimental.grounding.source_uris"
+}
+/** GCP Vertex agent attribute keys, consumed by the Vertex trace UI. */
+export declare enum GcpAttr {
+    INVOCATION_ID = "gcp.vertex.agent.invocation_id",
+    EVENT_ID = "gcp.vertex.agent.event_id",
+    ASSOCIATED_EVENT_IDS = "gcp.vertex.agent.associated_event_ids",
+    DATA = "gcp.vertex.agent.data"
+}
+/** OpenTelemetry HTTP client semantic-convention keys. */
+export declare enum HttpAttr {
+    REQUEST_METHOD = "http.request.method",
+    RESPONSE_STATUS_CODE = "http.response.status_code",
+    REQUEST_BODY_CONTENT = "http.request.body.content",
+    RESPONSE_BODY_CONTENT = "http.response.body.content",
+    /** Prefix of `http.request.header.<lowercased name>`. */
+    REQUEST_HEADER_PREFIX = "http.request.header.",
+    /** Prefix of `http.response.header.<lowercased name>`. */
+    RESPONSE_HEADER_PREFIX = "http.response.header.",
+    URL_FULL = "url.full",
+    SERVER_ADDRESS = "server.address",
+    SERVER_PORT = "server.port"
+}
+/** OpenTelemetry MCP semantic-convention keys. */
+export declare enum McpAttr {
+    SESSION_ID = "mcp.session.id",
+    PROTOCOL_VERSION = "mcp.protocol.version"
+}
+/** Standard OpenTelemetry error classification attribute key. */
+export declare const ERROR_TYPE_ATTR = "error.type";
+/** Standard OpenTelemetry end-user identifier attribute key. */
+export declare const USER_ID_ATTR = "user.id";
+/**
+ * Attribute on the top span of a trace that holds the caller's `traceparent`
+ * header, so a support request can be matched to the trace.
+ */
+export declare const SUPPORT_ID_ATTR = "supportID";
+/** Instrumentation scope name identifying ADK as the emitter. */
+export declare const GEN_AI_SYSTEM_VALUE = "gcp.vertex.agent";
+/** Schema URL of the OpenTelemetry semantic conventions ADK emits. */
+export declare const SCHEMA_URL = "https://opentelemetry.io/schemas/1.44.0";

package/dist/types/telemetry/api/internal/common/config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Where GenAI message content is recorded, as named by
+ * `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`.
+ */
+export type ContentCapturingMode = 'NO_CONTENT' | 'EVENT_ONLY' | 'SPAN_ONLY' | 'SPAN_AND_EVENT';
+/** A named group of experimental telemetry that can be enabled on its own. */
+export type ExperimentalFeature = 'skills' | 'workflow' | 'context_cache' | 'grounding' | 'mcp' | 'token_usage' | 'compaction';
+/**
+ * Per-run telemetry overrides, set through `RunConfig.telemetry`.
+ *
+ * A field left unset falls back to the environment variable it overrides.
+ * When `ADK_TELEMETRY_IGNORE_RUN_CONFIG` is `true` or `1`, every field is
+ * ignored and the environment decides.
+ */
+export interface TelemetryConfig {
+    /** Overrides `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`. */
+    readonly captureMessageContent?: ContentCapturingMode;
+    /**
+     * Overrides `ADK_EXPERIMENTAL_TELEMETRY`. `true` enables every experimental
+     * feature for the run, and `false` disables every one, including those named
+     * in `ADK_EXPERIMENTAL_TELEMETRY_FEATURES` or `experimentalFeaturesOptIn`.
+     */
+    readonly adkExperimentalTelemetryOptIn?: boolean;
+    /**
+     * Overrides `ADK_EXPERIMENTAL_TELEMETRY_FEATURES`: exactly these features
+     * are enabled for the run. Unrecognized names are ignored, and a list with
+     * no recognized name falls back to the environment.
+     */
+    readonly experimentalFeaturesOptIn?: readonly ExperimentalFeature[];
+}
+/** The telemetry decisions for one scope. */
+export interface ResolvedTelemetryConfig {
+    /** Where message content is recorded. */
+    readonly contentCapturingMode: ContentCapturingMode;
+    /** Whether every experimental feature is enabled. */
+    readonly experimentalTelemetry: boolean;
+    /** Features enabled one by one. */
+    readonly experimentalFeatures: ReadonlySet<ExperimentalFeature>;
+}
+/** Whether an environment variable is `true` or `1`, ignoring case and spaces. */
+export declare function isTruthyEnv(name: string): boolean;
+/**
+ * Resolves the telemetry configuration of one scope.
+ *
+ * Each value comes from `overrides` when it sets it, else from its environment
+ * variable, else from its default. `ADK_TELEMETRY_IGNORE_RUN_CONFIG` makes the
+ * environment win over every override. The environment is read on each call
+ * rather than at import, so a change to it applies to the next scope.
+ */
+export declare function resolveTelemetryConfig(overrides?: TelemetryConfig): ResolvedTelemetryConfig;
+/** Whether message content goes on log records (`EVENT_ONLY`, `SPAN_AND_EVENT`). */
+export declare function shouldAddContentToLogs(config: ResolvedTelemetryConfig): boolean;
+/** Whether message content goes on spans (`SPAN_ONLY`, `SPAN_AND_EVENT`). */
+export declare function shouldAddContentToSpans(config: ResolvedTelemetryConfig): boolean;
+/** Whether the named experimental feature is enabled. */
+export declare function isExperimentalFeatureEnabled(config: ResolvedTelemetryConfig, feature: ExperimentalFeature): boolean;

package/dist/types/telemetry/api/internal/common/error.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Normalizes a candidate error classification by trimming strings and
+ * stringifying finite numbers.
+ *
+ * @param value The candidate classification value.
+ * @returns The non-empty trimmed classification string, or undefined if invalid.
+ */
+export declare function normalizeErrorClassification(value: unknown): string | undefined;
+/**
+ * Resolves a stable error classification suitable for the OpenTelemetry
+ * `error.type` attribute without using the potentially sensitive error message.
+ *
+ * @param error The thrown value.
+ * @returns The explicit ADK error type, GenAI API status, or error class name.
+ */
+export declare function resolveErrorType(error: unknown): string;
+/**
+ * Gets an explicitly reported error type from a tool response object.
+ *
+ * Tools may return an error payload instead of throwing. Only the dedicated
+ * error type or error code field is copied to telemetry; the payload itself is
+ * never used as the error classification.
+ */
+export declare function getToolResponseErrorType(result: unknown): string | undefined;

package/dist/types/telemetry/api/internal/common/finish_reason.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FinishReason } from '@google/genai';
+/**
+ * Whether the model reported why generation stopped.
+ *
+ * The unspecified value is the proto3 zero value, so a response that carries
+ * it has not reported a reason.
+ */
+export declare function isReportedFinishReason(finishReason: FinishReason | undefined): finishReason is FinishReason;
+/**
+ * Maps a finish reason to the `finish_reason` of a GenAI output message, or
+ * `''` when none was reported.
+ */
+export declare function toOutputMessageFinishReason(finishReason: FinishReason | undefined): string;

package/dist/types/telemetry/api/internal/common/genai_messages.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AnyValue, AnyValueMap } from '@opentelemetry/api-logs';
+import type { LlmRequest } from '../../../../models/llm_request.js';
+import type { LlmResponse } from '../../../../models/llm_response.js';
+import { GenAiAttr } from './attributes.js';
+/** Message content and tool definitions of one model call, by attribute key. */
+export type OperationDetails = Partial<Record<GenAiAttr.INPUT_MESSAGES | GenAiAttr.OUTPUT_MESSAGES | GenAiAttr.SYSTEM_INSTRUCTIONS | GenAiAttr.TOOL_DEFINITIONS, AnyValue[]>>;
+/**
+ * Builds the operation details a model request contributes: input messages,
+ * system instructions and tool definitions.
+ */
+export declare function buildRequestOperationDetails(llmRequest: LlmRequest): OperationDetails;
+/**
+ * Builds the output message for one model response, or `undefined` when it
+ * carries no content.
+ */
+export declare function buildOutputMessage(llmResponse: LlmResponse): AnyValueMap | undefined;
+/**
+ * Returns the view of the operation details that carries no message content:
+ * the tool definitions without their parameter schemas.
+ */
+export declare function withoutContent(details: OperationDetails): OperationDetails;

package/dist/types/telemetry/api/internal/common/http_exchange.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** One HTTP request and its response, made safe to record. */
+export interface HttpExchange {
+    /** The request method, in upper case. */
+    readonly method: string;
+    /** The request URL without userinfo, with every query value redacted. */
+    readonly url: string;
+    /** The URL host name, without IPv6 brackets. */
+    readonly serverAddress: string;
+    /** The URL port, when the URL names one. */
+    readonly serverPort?: number;
+    /** The `sessionId` or `session_id` query value of the request URL. */
+    readonly querySessionId?: string;
+    readonly statusCode: number;
+    /** Request headers by lowercased name, with credentials redacted. */
+    readonly requestHeaders: ReadonlyMap<string, string>;
+    /** Response headers by lowercased name, with credentials redacted. */
+    readonly responseHeaders: ReadonlyMap<string, string>;
+    /**
+     * The request body, truncated. Absent when bodies are not captured, or when
+     * the body cannot be read without consuming it.
+     */
+    readonly requestBody?: string;
+    /**
+     * The response body, truncated, or a marker for a body that is not read.
+     * Absent when bodies are not captured.
+     */
+    readonly responseBody?: string;
+}
+/** Parameters for {@link captureHttpExchange}. */
+export interface CaptureHttpExchangeParams {
+    readonly url: string | URL;
+    readonly init?: Parameters<typeof fetch>[1];
+    readonly response: Response;
+    /** Whether to read the request and response bodies. */
+    readonly captureBodies: boolean;
+}
+/**
+ * Captures one HTTP exchange for recording.
+ *
+ * Everything it needs from `response` is taken before it returns, so the
+ * caller may hand the response on as soon as this returns: the response body
+ * is read from a clone in the background, and never for an event stream,
+ * which does not end.
+ */
+export declare function captureHttpExchange({ url, init, response, captureBodies, }: CaptureHttpExchangeParams): Promise<HttpExchange>;

package/dist/types/telemetry/api/internal/common/provider_name.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Returns the `gen_ai.system` name of the Gemini backend in use.
+ */
+export declare function guessGeminiSystemName(): string;
+/**
+ * Returns the `gen_ai.provider.name` of the provider serving `model`.
+ *
+ * A `<provider>/<model>` id names its provider in the prefix. Otherwise, and
+ * for Gemini models, the name follows the Gemini backend in use.
+ */
+export declare function resolveProviderName(model: string | undefined): string;

package/dist/types/telemetry/api/internal/common/redaction.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Returns a copy of a JSON-like payload with credential secrets removed.
+ *
+ * Removes the secret fields of anything shaped like an auth credential or auth
+ * config, wherever it is nested: a credential object, the arguments and
+ * response of a credential request, and the credential-carrying fields of
+ * event actions.
+ */
+export declare function redactCredentialSecrets(value: unknown): unknown;

package/dist/types/telemetry/api/internal/common/serialization.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Convert any JavaScript object to a JSON-serializable string.
+ *
+ * @param obj The object to serialize.
+ * @returns The JSON-serialized object string or '<not serializable>' if the object cannot be serialized.
+ */
+export declare function safeJsonSerialize(obj: unknown): string;
+/**
+ * Determines whether to add live request content to the `send_data` span.
+ *
+ * @returns false only when ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS is explicitly set to 'false' or '0'
+ */
+export declare function shouldAddRequestResponseToSpans(): boolean;

package/dist/types/telemetry/api/internal/common/token_usage.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GenerateContentResponseUsageMetadata } from '@google/genai';
+import type { Attributes } from '@opentelemetry/api';
+/** Description of the `input_tokens` metric bucket. */
+export declare const INPUT_TOKENS_MEANING: string;
+/** Description of the `output_tokens` metric bucket. */
+export declare const OUTPUT_TOKENS_MEANING: string;
+/** Description of the `total_tokens` metric bucket. */
+export declare const TOTAL_TOKENS_MEANING: string;
+/** Description of the `cache_read.input_tokens` metric bucket. */
+export declare const CACHE_READ_INPUT_TOKENS_MEANING = "Input tokens served from a provider-managed cache.";
+/** Description of the `reasoning.output_tokens` metric bucket. */
+export declare const REASONING_OUTPUT_TOKENS_MEANING = "Output tokens spent on reasoning (chain-of-thought / extended thinking).";
+/** Description of the `tool.input_tokens` metric bucket. */
+export declare const TOOL_INPUT_TOKENS_MEANING: string;
+/**
+ * GenAI token usage, either one model call's or a sum over several.
+ *
+ * Input tokens sum the prompt and server-side tool results; output tokens sum
+ * candidates and reasoning. A bucket that nothing reported is `undefined`
+ * rather than zero: {@link asAttributes} omits it and {@link add} keeps it
+ * `undefined` until some call reports it.
+ */
+export declare class TokenUsage {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    reasoning?: number;
+    toolInput?: number;
+    constructor(usage?: GenerateContentResponseUsageMetadata);
+    /** Folds another call's usage into these totals, bucket by bucket. */
+    add(other: TokenUsage): void;
+    /**
+     * Input plus output tokens, derived from those two rather than taken from
+     * the model-reported total.
+     */
+    totalTokenUsage(): number;
+    /**
+     * Returns the GenAI token usage attributes for the reported buckets,
+     * omitting `undefined` buckets and preserving `0`.
+     */
+    asAttributes(): Attributes;
+}

package/dist/types/telemetry/api/internal/logs/inference.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Span } from '@opentelemetry/api';
+import type { LogAttributes } from '@opentelemetry/api-logs';
+/**
+ * Emits the `gen_ai.client.inference.operation.details` record of one model
+ * call, parented to its `generate_content` span.
+ *
+ * The span is named explicitly rather than taken from the active context,
+ * which need not hold it when the call ends.
+ */
+export declare function emitInferenceOperationDetails(span: Span, attributes: LogAttributes): void;

package/dist/types/telemetry/api/internal/logs/logger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Logger } from '@opentelemetry/api-logs';
+/**
+ * Returns the ADK logger from the global `LoggerProvider`.
+ *
+ * Resolved on every call rather than once at import, so records reach a
+ * provider the application registers after importing ADK.
+ */
+export declare function getTelemetryLogger(): Logger;

package/dist/types/telemetry/api/internal/logs/mcp.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Context } from '@opentelemetry/api';
+/** What to record about MCP HTTP exchanges, read from the environment. */
+export interface McpHttpExchangeSettings {
+    readonly captureBodies: boolean;
+    readonly requestHeaderPatterns: readonly RegExp[];
+    readonly responseHeaderPatterns: readonly RegExp[];
+}
+/** Reads the MCP HTTP exchange settings from the environment. */
+export declare function readMcpHttpExchangeSettings(): McpHttpExchangeSettings;
+/** Parameters for {@link reportMcpHttpExchange}. */
+export interface ReportMcpHttpExchangeParams {
+    readonly url: string | URL;
+    readonly init?: Parameters<typeof fetch>[1];
+    readonly response: Response;
+    readonly settings: McpHttpExchangeSettings;
+    /** The context the request was sent in, which parents the record. */
+    readonly context: Context;
+}
+/**
+ * Emits the `adk.experimental.mcp.http.client.response.end` record of one MCP
+ * HTTP exchange.
+ *
+ * Takes what it needs from `response` before its first await, so the caller
+ * can hand the response on at once and leave the returned promise running.
+ */
+export declare function reportMcpHttpExchange({ url, init, response, settings, context, }: ReportMcpHttpExchangeParams): Promise<void>;

package/dist/types/telemetry/api/internal/metrics/agent.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Totals } from '../common/accumulators.js';
+import { type ResolvedTelemetryConfig } from '../common/config.js';
+/** Advisory bucket boundaries for `gen_ai.invoke_agent.duration`. */
+export declare const AGENT_DURATION_BUCKETS: readonly number[];
+/** Parameters for {@link recordAgentDuration}. */
+export interface RecordAgentDurationParams {
+    readonly agentName: string;
+    readonly durationSeconds: number;
+    readonly errorType?: string;
+}
+/** Records `gen_ai.invoke_agent.duration` at the end of an agent invocation. */
+export declare function recordAgentDuration({ agentName, durationSeconds, errorType, }: RecordAgentDurationParams): void;
+/** Parameters for {@link recordAgentTotals}. */
+export interface RecordAgentTotalsParams {
+    readonly agentName: string;
+    readonly totals: Totals;
+    readonly config: ResolvedTelemetryConfig;
+}
+/**
+ * Records the per-agent call, skill-load, and token totals accumulated over
+ * one agent invocation.
+ */
+export declare function recordAgentTotals({ agentName, totals, config, }: RecordAgentTotalsParams): void;

package/dist/types/telemetry/api/internal/metrics/inference_start_hook.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Tells the installed metric reader, if any, that a model call has started.
+ *
+ * Never throws: a failure in the hook is logged and does not reach the model
+ * call that triggered it.
+ */
+export declare function notifyInferenceStart(): void;

package/dist/types/telemetry/api/internal/metrics/meters.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Attributes, type Histogram, type Meter } from '@opentelemetry/api';
+import { type TokenUsage } from '../common/token_usage.js';
+/**
+ * Advisory bucket boundaries for per-invocation and per-workflow call-count
+ * histograms. Upper-inclusive, so the leading `0` buckets exact zeros on their
+ * own.
+ */
+export declare const CALL_COUNT_BUCKETS: readonly number[];
+/**
+ * Advisory bucket boundaries for input, total, cache-read, and tool-input
+ * token histograms.
+ */
+export declare const INPUT_TOKEN_BUCKETS: readonly number[];
+/**
+ * Advisory bucket boundaries for output and reasoning token histograms.
+ */
+export declare const OUTPUT_TOKEN_BUCKETS: readonly number[];
+/**
+ * Lazily builds and caches one set of domain instruments per registered
+ * `MeterProvider`, so a provider registered after ADK is imported still
+ * receives metrics under the ADK instrumentation scope and schema URL.
+ */
+export declare function cachedInstruments<T>(create: (meter: Meter) => T): () => T;
+/** Parameters for {@link createHistogram}. */
+export interface CreateHistogramParams {
+    readonly meter: Meter;
+    readonly name: string;
+    readonly unit: string;
+    readonly description: string;
+    readonly buckets?: readonly number[];
+}
+/** Creates a histogram with optional advisory bucket boundaries. */
+export declare function createHistogram({ meter, name, unit, description, buckets, }: CreateHistogramParams): Histogram;
+/** The six token histograms of one family (`invoke_agent` or `invoke_workflow`). */
+export interface TokenHistograms {
+    readonly input: Histogram;
+    readonly output: Histogram;
+    readonly total: Histogram;
+    readonly cacheRead: Histogram;
+    readonly reasoning: Histogram;
+    readonly toolInput: Histogram;
+}
+/**
+ * Builds the six token histograms for `prefix`, interpolating the shared token
+ * meaning descriptions with `scopeDescription`.
+ */
+export declare function createTokenHistograms(meter: Meter, prefix: string, scopeDescription: string): TokenHistograms;
+/**
+ * Records all six token histograms for a scope where at least one model call
+ * reported token usage. Unreported buckets record `0`.
+ */
+export declare function recordTokenHistograms(histograms: TokenHistograms, usage: TokenUsage, attributes: Attributes): void;

package/dist/types/telemetry/api/internal/metrics/tool.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Skill } from '../../../../skills/skill.js';
+import { type ResolvedTelemetryConfig } from '../common/config.js';
+/** Advisory bucket boundaries for `gen_ai.execute_tool.duration`. */
+export declare const TOOL_DURATION_BUCKETS: readonly number[];
+/** Parameters for {@link recordToolDuration}. */
+export interface RecordToolDurationParams {
+    readonly agentName: string;
+    readonly toolName: string;
+    readonly toolType: string;
+    readonly durationSeconds: number;
+    readonly errorType?: string;
+}
+/** Records `gen_ai.execute_tool.duration` at the end of a tool call. */
+export declare function recordToolDuration({ agentName, toolName, toolType, durationSeconds, errorType, }: RecordToolDurationParams): void;
+/** Parameters for {@link recordSkillLoad}. */
+export interface RecordSkillLoadParams {
+    readonly agentName: string;
+    readonly skill?: Skill;
+    readonly errorType?: string;
+    readonly config: ResolvedTelemetryConfig;
+}
+/**
+ * Records one `adk.experimental.skill.loads` increment when `skills` is
+ * enabled, bounding unresolved skill names to `<hallucinated>`.
+ */
+export declare function recordSkillLoad({ agentName, skill, errorType, config, }: RecordSkillLoadParams): void;
+/** Parameters for {@link recordSkillScriptExecution}. */
+export interface RecordSkillScriptExecutionParams {
+    readonly agentName: string;
+    readonly skill?: Skill;
+    readonly scriptPath: string;
+    readonly config: ResolvedTelemetryConfig;
+}
+/**
+ * Records one `adk.experimental.skill.script.executions` increment when
+ * `skills` is enabled, bounding unresolved skill names and script paths to
+ * `<hallucinated>`.
+ */
+export declare function recordSkillScriptExecution({ agentName, skill, scriptPath, config, }: RecordSkillScriptExecutionParams): void;

package/dist/types/telemetry/api/internal/metrics/workflow.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Totals } from '../common/accumulators.js';
+import { type ResolvedTelemetryConfig } from '../common/config.js';
+/** Parameters for {@link recordWorkflowDuration}. */
+export interface RecordWorkflowDurationParams {
+    readonly workflowName: string;
+    readonly durationSeconds: number;
+    readonly nested: boolean;
+    readonly errorType?: string;
+}
+/**
+ * Records `gen_ai.invoke_workflow.duration` at the end of a workflow
+ * invocation.
+ */
+export declare function recordWorkflowDuration({ workflowName, durationSeconds, nested, errorType, }: RecordWorkflowDurationParams): void;
+/** Parameters for {@link recordWorkflowTotals}. */
+export interface RecordWorkflowTotalsParams {
+    readonly rootAgentName: string;
+    readonly workflowName: string;
+    readonly nested: boolean;
+    readonly totals: Totals;
+    readonly config: ResolvedTelemetryConfig;
+}
+/**
+ * Records the inclusive call, skill-load, compaction, and token totals for one
+ * workflow invocation when the `workflow` experimental feature is enabled.
+ */
+export declare function recordWorkflowTotals({ rootAgentName, workflowName, nested, totals, config, }: RecordWorkflowTotalsParams): void;

package/dist/types/telemetry/api/internal/trace/agent.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Attributes } from '@opentelemetry/api';
+import type { BaseAgent } from '../../../../agents/base_agent.js';
+/** Parameters for {@link buildAgentInvocationAttributes}. */
+export interface AgentInvocationAttributesParams {
+    readonly agent: BaseAgent;
+    readonly sessionId: string | undefined;
+}
+/** Builds the attributes of an `invoke_agent` span. */
+export declare function buildAgentInvocationAttributes({ agent, sessionId, }: AgentInvocationAttributesParams): Attributes;

package/dist/types/telemetry/api/internal/trace/compaction.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Attributes, Span } from '@opentelemetry/api';
+import type { Event } from '../../../../events/event.js';
+/** Parameters for {@link startCompactionSpan}. */
+export interface StartCompactionSpanParams {
+    readonly sessionId: string;
+    readonly trigger: string;
+}
+/** Starts a `compact_events {trigger}` span under the active context. */
+export declare function startCompactionSpan({ sessionId, trigger, }: StartCompactionSpanParams): Span;
+/**
+ * Builds the result attributes of a compaction from the session events before
+ * and after it ran: the summary event it added, the time range it covers, and
+ * how many of the earlier events fall in that range.
+ */
+export declare function buildCompactionResultAttributes(eventsBefore: readonly Event[], eventsAfter: readonly Event[]): Attributes;