@google/adk 2.3.0 → 2.5.0

package/dist/types/telemetry/api/instrumentation.d.ts

@@ -0,0 +1,259 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import type { BaseAgent } from '../../agents/base_agent.js';
+import type { InvocationContext } from '../../agents/invocation_context.js';
+import type { RunConfig } from '../../agents/run_config.js';
+import type { Event } from '../../events/event.js';
+import type { LlmRequest } from '../../models/llm_request.js';
+import type { LlmResponse } from '../../models/llm_response.js';
+import type { ContextCompactionTrigger } from '../../plugins/base_plugin.js';
+import type { Skill } from '../../skills/skill.js';
+import type { BaseTool } from '../../tools/base_tool.js';
+import type { BaseNode } from '../../workflow/base_node.js';
+import { type IncomingHeaders } from './internal/trace/propagation.js';
+export type { ContentCapturingMode, ExperimentalFeature, TelemetryConfig, } from './internal/common/config.js';
+export type { IncomingHeaders } from './internal/trace/propagation.js';
+/** Parameters for starting an invocation with {@link recordInvocation}. */
+export interface RecordInvocationParams {
+    /** The runner's root agent or workflow. */
+    readonly entrypoint: BaseNode;
+    /** The session the invocation runs in. */
+    readonly sessionId: string;
+    /** The run's config, whose `telemetry` overrides apply to the invocation. */
+    readonly runConfig?: RunConfig;
+}
+/**
+ * Wraps a runner invocation in its root `invoke_workflow {entrypoint}` span.
+ *
+ * Every workflow started inside the invocation is nested below this span. A
+ * workflow entrypoint runs inside it rather than opening a second one.
+ */
+export declare function recordInvocation<T>({ entrypoint, sessionId, runConfig }: RecordInvocationParams, createGenerator: () => AsyncGenerator<T, void, void>): AsyncGenerator<T, void, void>;
+/** Parameters for starting an `invoke_agent` instrumentation scope. */
+export interface RecordAgentInvocationParams {
+    readonly agent: BaseAgent;
+    /** The context the agent was invoked with. */
+    readonly invocationContext: InvocationContext;
+}
+/**
+ * Wraps an agent invocation in an `invoke_agent {agent.name}` span.
+ */
+export declare function recordAgentInvocation<T>({ agent, invocationContext }: RecordAgentInvocationParams, createGenerator: () => AsyncGenerator<T, void, void>): AsyncGenerator<T, void, void>;
+/** Parameters for recording one model call with {@link recordInference}. */
+export interface RecordInferenceParams {
+    readonly invocationContext: InvocationContext;
+    readonly llmRequest: LlmRequest;
+    /** The event the model's responses are merged into. */
+    readonly modelResponseEvent: Event;
+}
+/**
+ * Wraps one model call in a `generate_content {model}` span and its
+ * `gen_ai.client.inference.operation.details` log record.
+ *
+ * Returns the model's responses unchanged. The span is current only while the
+ * model stream is being pulled, never while the caller handles a response, and
+ * it ends at the first response that reports a finish reason, before that
+ * response is returned. If the stream ends, fails or is closed before one
+ * arrives, the span ends then. Each call emits exactly one log record, while
+ * the span is still open.
+ */
+export declare function recordInference(params: RecordInferenceParams, createStream: () => AsyncGenerator<LlmResponse, void, void>): AsyncGenerator<LlmResponse, void, void>;
+/** Parameters for recording a live `send_data` span. */
+export interface RecordSendDataParams {
+    readonly invocationContext: InvocationContext;
+    readonly eventId: string;
+    readonly data: Content[];
+}
+/**
+ * Wraps an async operation in a `send_data` span and records the live data
+ * payload attributes when the operation completes.
+ */
+export declare function recordSendData<T>(params: RecordSendDataParams, fn: () => Promise<T>): Promise<T>;
+/** Parameters for starting an `execute_tool` instrumentation scope. */
+export interface RecordToolExecutionParams {
+    readonly tool: BaseTool;
+    readonly args: Record<string, unknown>;
+    readonly invocationContext: InvocationContext;
+}
+/** Parameters for recording a completed tool execution on its scope. */
+export interface ToolExecutionSuccessParams {
+    readonly functionResponseEvent?: Event;
+    /**
+     * The raw value returned by the tool before normalization into a
+     * `functionResponse` event, used to inspect any response-reported error type.
+     */
+    readonly rawResult: unknown;
+}
+/** Scope handle passed to the body of {@link recordToolExecution}. */
+export interface ToolExecutionScope {
+    /**
+     * Records the tool's response, including an error the tool reported in it
+     * rather than throwing.
+     */
+    recordSuccess(params: ToolExecutionSuccessParams): void;
+}
+/**
+ * Wraps a single tool call in an `execute_tool {tool.name}` span.
+ *
+ * An error that escapes `fn` is recorded on the span as `error.type` and an
+ * ERROR status, as is an error the tool reports in its response. Skill tools
+ * running inside report to the span through {@link recordSkillActivity}.
+ */
+export declare function recordToolExecution<T>({ tool, args, invocationContext }: RecordToolExecutionParams, fn: (scope: ToolExecutionScope) => Promise<T>): Promise<T>;
+/** What a skill tool is doing, reported with {@link recordSkillActivity}. */
+export type SkillActivity = {
+    readonly kind: 'load';
+    readonly skillName: string;
+} | {
+    readonly kind: 'resource';
+    readonly skillName: string;
+    readonly resourcePath: string;
+} | {
+    readonly kind: 'script';
+    readonly skillName: string;
+    readonly scriptPath: string;
+};
+/** Handle returned by {@link recordSkillActivity}. */
+export interface SkillActivityScope {
+    /** Records the skill the tool resolved. */
+    recordSkill(skill: Skill): void;
+}
+/**
+ * Reports what a skill tool is doing to the `execute_tool` span it runs
+ * under, which is renamed after the skill and records its attributes when the
+ * tool call ends.
+ *
+ * Does nothing outside a tool call. A second report in the same tool call
+ * replaces the first.
+ */
+export declare function recordSkillActivity(activity: SkillActivity): SkillActivityScope;
+/** Parameters for recording a merged tool calls span. */
+export interface RecordMergedToolCallsParams {
+    /** The id of the event that merges the parallel tool responses. */
+    readonly responseEventId: string;
+}
+/**
+ * Starts and immediately ends an `execute_tool (merged)` span for parallel
+ * tool calls whose responses were merged into one event.
+ */
+export declare function recordMergedToolCalls({ responseEventId, }: RecordMergedToolCallsParams): void;
+/**
+ * A synchronously started span scope for workflow orchestration.
+ *
+ * Workflow and node scopes return this handle instead of wrapping a callback.
+ * Their spans must start at the moment the work is scheduled, and the scope
+ * must hand the caller's promise back unchanged: an `async` wrapper adds
+ * promise ticks, which changes how concurrently scheduled nodes interleave.
+ */
+export interface SyncStartedScope {
+    /**
+     * Runs `fn` with this scope's span as the active span and returns its result
+     * as is, without awaiting it.
+     */
+    run<T>(fn: () => T): T;
+    /**
+     * Ends the span, with an ERROR status when `error` is given. Safe to call
+     * more than once; only the first call counts.
+     */
+    end(error?: unknown): void;
+}
+/** Parameters for starting an `invoke_workflow` instrumentation scope. */
+export interface RecordWorkflowInvocationParams {
+    readonly workflow: BaseNode;
+    readonly sessionId: string;
+}
+/**
+ * Starts the `invoke_workflow {workflow.name}` scope of a workflow run,
+ * synchronously.
+ *
+ * The workflow the runner was entered at runs in the runner's span instead,
+ * so its scope opens nothing. A workflow started inside another workflow is
+ * marked nested. The caller runs the orchestration through `scope.run` and
+ * calls `scope.end()` once it settles.
+ */
+export declare function recordWorkflowInvocation({ workflow, sessionId, }: RecordWorkflowInvocationParams): SyncStartedScope;
+/** Parameters for starting a workflow node's instrumentation scope. */
+export interface RecordNodeInvocationParams {
+    readonly node: BaseNode;
+    /** The name the node runs under, which may differ from `node.name`. */
+    readonly nodeName: string;
+    readonly sessionId: string;
+}
+/** Scope handle returned by {@link recordNodeInvocation}. */
+export interface NodeInvocationScope extends SyncStartedScope {
+    /** Records an event the node emitted. */
+    recordEvent(event: Event): void;
+}
+/**
+ * Starts the scope of one workflow node run, synchronously.
+ *
+ * A plain node runs in an `invoke_node {nodeName}` span that records the ids
+ * of the events it emitted. An agent or workflow node opens no node span: its
+ * own `invoke_agent` or `invoke_workflow` span stands for it.
+ *
+ * The span's parent is the span active at the call, so call this when the node
+ * is scheduled. The caller runs the node body through `scope.run` and calls
+ * `scope.end()` when the node work finishes.
+ */
+export declare function recordNodeInvocation({ node, nodeName, sessionId, }: RecordNodeInvocationParams): NodeInvocationScope;
+/** Parameters for recording a context compaction. */
+export interface RecordCompactionParams {
+    readonly invocationContext: InvocationContext;
+    readonly trigger: ContextCompactionTrigger;
+}
+/**
+ * Wraps a context compaction in a `compact_events {trigger}` span, recording
+ * the summary event it added to the session.
+ */
+export declare function recordCompaction<T>({ invocationContext, trigger }: RecordCompactionParams, fn: () => Promise<T>): Promise<T>;
+/** A `fetch` as the MCP HTTP transports call it. */
+export type McpFetch = (url: string | URL, init?: Parameters<typeof globalThis.fetch>[1]) => Promise<Response>;
+/**
+ * Returns a `fetch` for an MCP HTTP transport that reports each exchange as
+ * an `adk.experimental.mcp.http.client.response.end` log record, parented to
+ * the span active when the request was sent.
+ *
+ * Returns `fetch` unchanged, `undefined` included, unless the experimental
+ * `mcp` telemetry feature is enabled in the environment, which is read when
+ * this is called, so call it when the transport is built. The returned
+ * function sends each request with `fetch`, or the global `fetch` when that is
+ * `undefined`, and resolves with its response as soon as it arrives: the
+ * record is written in the background, and a failure to write it is logged,
+ * never thrown.
+ */
+export declare function instrumentMcpFetch(fetch: McpFetch | undefined): McpFetch | undefined;
+/** A `fetch`-compatible function. */
+export type FetchFunction = (input: Parameters<typeof globalThis.fetch>[0], init?: Parameters<typeof globalThis.fetch>[1]) => Promise<Response>;
+/**
+ * Returns a `fetch` that sends the active trace context with each request.
+ *
+ * At each call, the globally registered propagator writes the active context
+ * into the request headers: W3C `traceparent` and `tracestate` by default. A
+ * header the caller already sets is kept. When the propagator writes nothing,
+ * for example with no active trace, the request is sent with its arguments
+ * unchanged. A propagator error is logged, never thrown.
+ *
+ * @param fetchImpl The `fetch` that sends the request. Defaults to the global
+ *     `fetch`, read at each call.
+ */
+export declare function propagateTraceContext(fetchImpl?: FetchFunction): FetchFunction;
+/**
+ * Runs `fn` in the trace context that an incoming request carries.
+ *
+ * When no span is active, the globally registered propagator reads the
+ * headers (W3C `traceparent` and `tracestate` by default), and a valid remote
+ * span becomes the parent of the invocation spans `fn` starts. An already
+ * active span, such as an HTTP server span or a remote parent set earlier,
+ * stays the parent, and the headers are ignored. Missing or malformed headers
+ * leave the context unchanged; a propagator error is logged, never thrown.
+ *
+ * @param headers The incoming request headers, such as Node's
+ *     `IncomingMessage.headers`.
+ * @param fn The request handler to run.
+ * @returns What `fn` returns.
+ */
+export declare function runWithRemoteTraceContext<T>(headers: IncomingHeaders, fn: () => T): T;

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

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Context } from '@opentelemetry/api';
+import type { ResolvedTelemetryConfig } from './config.js';
+import { TokenUsage } from './token_usage.js';
+declare const WORKFLOW_FRAME_SYMBOL: unique symbol;
+/** An accumulator's totals at flush time. */
+export interface Totals {
+    /** `undefined` until a model call reports usage (not the same as zero). */
+    tokens?: TokenUsage;
+    inferenceCalls: number;
+    toolCalls: number;
+    skillLoads: number;
+    compactions: number;
+}
+/** State accumulated across one agent invocation or one workflow. */
+export interface Accumulator {
+    readonly totals: Totals;
+}
+/**
+ * State accumulated across one `invoke_workflow`, root or nested.
+ *
+ * The `parent` chain is walked when a call records against every enclosing
+ * workflow; its presence is what `gen_ai.workflow.nested` reports.
+ */
+export interface WorkflowFrame extends Accumulator {
+    readonly [WORKFLOW_FRAME_SYMBOL]: true;
+    readonly parent: WorkflowFrame | undefined;
+    /** The agent or workflow the turn entered at, inherited by nested workflows. */
+    readonly rootAgentName: string;
+    readonly workflowName: string;
+    /** The config the turn was claimed under, inherited by nested workflows. */
+    readonly config: ResolvedTelemetryConfig;
+    /**
+     * The runner's workflow entrypoint, which runs inside this frame instead of
+     * opening its own. Cleared once that workflow has claimed it.
+     */
+    entrypoint: object | undefined;
+}
+/**
+ * Opens an agent accumulator frame on `parentContext`, so model and tool calls
+ * running inside count their exclusive totals against this agent invocation.
+ */
+export declare function openAgentFrame(parentContext?: Context): {
+    readonly frame: Accumulator;
+    readonly context: Context;
+};
+/** Parameters for {@link openWorkflowFrame}. */
+export interface OpenWorkflowFrameParams {
+    readonly workflowName: string;
+    /** The config to use when this is the root workflow frame. */
+    readonly config: ResolvedTelemetryConfig;
+    readonly entrypoint?: object;
+    readonly parentContext?: Context;
+}
+/**
+ * Opens a workflow accumulator frame on `parentContext`, linked to any
+ * enclosing workflow frame and inheriting its root agent name and telemetry
+ * config.
+ */
+export declare function openWorkflowFrame({ workflowName, config, entrypoint, parentContext, }: OpenWorkflowFrameParams): {
+    readonly frame: WorkflowFrame;
+    readonly context: Context;
+};
+/**
+ * Hands the runner's entrypoint frame to the workflow it was opened for, once.
+ *
+ * @returns The context to run the workflow under, or `undefined` when
+ *     `workflow` is not the unclaimed entrypoint of the enclosing frame.
+ */
+export declare function claimEntrypointWorkflowFrame(workflow: object, ctx?: Context): Context | undefined;
+/**
+ * Every accumulator a call belongs to, captured from the context when the call
+ * starts: the innermost agent (exclusive) and each enclosing workflow
+ * (inclusive).
+ */
+export interface CapturedAccumulators {
+    addInferenceCall(): void;
+    addToolCall(): void;
+    addSkillLoad(): void;
+    addCompaction(): void;
+    addTokens(usage: TokenUsage): void;
+}
+/**
+ * Captures the active agent and workflow accumulators from `ctx`.
+ */
+export declare function captureAccumulators(ctx?: Context): CapturedAccumulators;
+export {};

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;