@google/adk 2.3.0 → 2.5.0

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;

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

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Attributes, Span } from '@opentelemetry/api';
+import type { LlmRequest } from '../../../../models/llm_request.js';
+import type { LlmResponse } from '../../../../models/llm_response.js';
+import { type ResolvedTelemetryConfig } from '../common/config.js';
+import { type OperationDetails } from '../common/genai_messages.js';
+/** Parameters for {@link startInferenceSpan}. */
+export interface StartInferenceSpanParams {
+    readonly llmRequest: LlmRequest;
+    /** Attributes the span shares with the call's log record. */
+    readonly commonAttributes: Attributes;
+}
+/** Starts a `generate_content {model}` span under the active context. */
+export declare function startInferenceSpan({ llmRequest, commonAttributes, }: StartInferenceSpanParams): Span;
+/**
+ * Builds the attributes one model response contributes to both the span and
+ * the log record: its finish reason and its token usage.
+ */
+export declare function buildResponseAttributes(llmResponse: LlmResponse): Attributes;
+/** Records one model response on its `generate_content` span. */
+export declare function setInferenceResponseAttributes(span: Span, llmResponse: LlmResponse, config: ResolvedTelemetryConfig): void;
+/**
+ * Records the operation details of a model call on its span, as JSON: all of
+ * them when content capture includes spans, otherwise only the view without
+ * message content.
+ */
+export declare function setInferenceOperationDetails(span: Span, details: OperationDetails, config: ResolvedTelemetryConfig): void;

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import type { Span } from '@opentelemetry/api';
+import type { InvocationContext } from '../../../../agents/invocation_context.js';
+/** Parameters for recording live history `send_data` attributes on a span. */
+export interface SetSendDataAttributesParams {
+    /** The invocation context for the current agent run. */
+    readonly invocationContext: InvocationContext;
+    /** The ID of the event. */
+    readonly eventId: string;
+    /** A list of content objects. */
+    readonly data: Content[];
+}
+/**
+ * Sets `send_data` attributes on the given span.
+ */
+export declare function setSendDataAttributes(span: Span, { invocationContext, eventId, data }: SetSendDataAttributesParams): void;

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

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Span } from '@opentelemetry/api';
+import type { BaseNode } from '../../../../workflow/base_node.js';
+/**
+ * Whether a node is traced by a span of its own kind rather than by
+ * `invoke_node`: an agent opens `invoke_agent` and a workflow
+ * `invoke_workflow`.
+ */
+export declare function hasOwnInvocationSpan(node: BaseNode): boolean;
+/** Parameters for {@link startNodeSpan}. */
+export interface StartNodeSpanParams {
+    readonly nodeName: string;
+    readonly sessionId: string;
+}
+/** Starts an `invoke_node {nodeName}` span under the active context. */
+export declare function startNodeSpan({ nodeName, sessionId, }: StartNodeSpanParams): Span;
+/** Records the ids of the events a node emitted on its span, if it emitted any. */
+export declare function setAssociatedEventIds(span: Span, eventIds: readonly string[]): void;

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

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TextMapGetter } from '@opentelemetry/api';
+/** Incoming request headers, such as Node's `IncomingMessage.headers`. */
+export type IncomingHeaders = Readonly<Record<string, string | string[] | undefined>>;
+/**
+ * Reads incoming request headers for the propagator, matching names
+ * case-insensitively. An array value is returned as is; the W3C propagator
+ * reads its first element.
+ */
+export declare const INCOMING_HEADERS_GETTER: TextMapGetter<IncomingHeaders>;
+/**
+ * Returns the headers a `fetch(input, init)` call sends, with each injected
+ * header added unless the call already sets it.
+ *
+ * As in `fetch`, `init.headers` replaces the headers of a `Request` input
+ * when given, and the `Request` headers are kept otherwise.
+ */
+export declare function addMissingHeaders(input: Parameters<typeof globalThis.fetch>[0], init: Parameters<typeof globalThis.fetch>[1], injected: Readonly<Record<string, string>>): Headers;

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

@@ -0,0 +1,57 @@
+/**
+ * @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';
+import type { Skill } from '../../../../skills/skill.js';
+import type { BaseTool } from '../../../../tools/base_tool.js';
+import type { ResolvedTelemetryConfig } from '../common/config.js';
+/** The outcome of one tool call, as recorded on its `execute_tool` span. */
+export type ToolCallOutcome = {
+    readonly kind: 'response';
+    readonly functionResponseEvent?: Event;
+    /** An error type the tool reported in its response instead of throwing. */
+    readonly errorType?: string;
+} | {
+    readonly kind: 'error';
+    readonly errorType: string;
+};
+/** Parameters for {@link buildToolCallAttributes}. */
+export interface ToolCallAttributesParams {
+    readonly tool: BaseTool;
+    readonly args: Record<string, unknown>;
+    readonly agentName?: string;
+    readonly outcome: ToolCallOutcome;
+    readonly config: ResolvedTelemetryConfig;
+}
+/**
+ * Builds the attributes of an `execute_tool` span.
+ *
+ * The call arguments and result are message content, so they are recorded
+ * only when content capture includes spans, and the result has credential
+ * secrets removed.
+ */
+export declare function buildToolCallAttributes({ tool, args, agentName, outcome, config, }: ToolCallAttributesParams): Attributes;
+/** Builds the attributes of an `execute_tool (merged)` span. */
+export declare function buildMergedToolCallsAttributes(responseEventId: string): Attributes;
+/** What a skill tool reported about the skill it worked on. */
+export interface SkillReport {
+    /** The skill name the tool was asked for, which may not exist. */
+    readonly skillName: string;
+    /** The resource or script path, for a resource load or a script run. */
+    readonly resourceName?: string;
+    /** Whether the tool loaded the skill itself, as opposed to part of it. */
+    readonly isSkillLoad: boolean;
+    /** Whether the tool executed a skill script. */
+    readonly isSkillScript?: boolean;
+    /** The skill, once the tool has resolved it. */
+    readonly skill?: Skill;
+}
+/** Names an `execute_tool` span after the skill and resource it touched. */
+export declare function buildSkillSpanName(toolName: string, report: SkillReport): string;
+/** Builds the skill attributes of an `execute_tool` span. */
+export declare function buildSkillAttributes(report: SkillReport): Attributes;
+/** Records a skill on its `execute_tool` span: the span name and attributes. */
+export declare function setSkillSpanAttributes(span: Span, toolName: string, report: SkillReport): void;

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

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Context, type Span, type Tracer } from '@opentelemetry/api';
+/**
+ * Returns the ADK tracer from the global `TracerProvider`.
+ *
+ * Resolved on every call rather than once at import, like the logger, so the
+ * tracer carries the schema URL whichever provider the application registers
+ * and whenever it registers it.
+ */
+export declare function getTracer(): Tracer;
+/**
+ * Binds an async generator to OpenTelemetry context for trace propagation.
+ *
+ * @param ctx The OpenTelemetry context to bind the generator to.
+ * @param generator The async generator to be bound to the context.
+ * @returns A new async generator that executes all operations within the provided context.
+ */
+export declare function bindOtelContextToAsyncGenerator<T>(ctx: Context, generator: AsyncGenerator<T, void, void>): AsyncGenerator<T, void, void>;
+/**
+ * Records a failure on a span: the exception and an ERROR status.
+ *
+ * The status message is the error type rather than the error message, which
+ * can carry user data that the content capture setting does not gate. Only an
+ * `Error` instance is recorded as an exception; any other thrown value is
+ * recorded by its type alone.
+ */
+export declare function setSpanError(span: Span, error: unknown): void;

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Context, type Span } from '@opentelemetry/api';
+/** Parameters for {@link startWorkflowSpan}. */
+export interface StartWorkflowSpanParams {
+    readonly workflowName: string;
+    readonly sessionId: string;
+    readonly nested: boolean;
+    readonly parentContext?: Context;
+}
+/**
+ * Starts an `invoke_workflow {workflowName}` span.
+ *
+ * A workflow started inside another workflow is marked
+ * `gen_ai.workflow.nested`; the outermost one carries no such attribute. The
+ * top span of a trace also carries `supportID` when the request supplied one.
+ */
+export declare function startWorkflowSpan({ workflowName, sessionId, nested, parentContext, }: StartWorkflowSpanParams): Span;

package/dist/types/telemetry/export/agent_engine.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Runs `fn` in a context that continues an Agent Engine request trace.
+ *
+ * When `Google-Agent-Engine-Traceparent` holds a valid W3C traceparent and no
+ * span is active, the Agent Engine span becomes the remote parent of the
+ * spans `fn` starts. An invalid value is ignored. The `traceparent` header is
+ * recorded as the `supportID` attribute of the invocation's top span.
+ *
+ * Without either header, `fn` runs in the active context unchanged.
+ *
+ * @experimental (Experimental, subject to change)
+ *
+ * @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 runWithAgentEngineContext<T>(headers: Readonly<Record<string, string | string[] | undefined>>, fn: () => T): T;

package/dist/types/telemetry/export/agent_runtime.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { OTelHooks } from './setup.js';
+/**
+ * Hooks a server calls at the start and end of every request, so telemetry is
+ * exported while the request still holds the CPU.
+ *
+ * Neither hook throws, and {@link AgentRuntimeRequestHooks.onRequestEnd}
+ * never rejects: a telemetry failure never breaks the request.
+ *
+ * @experimental (Experimental, subject to change)
+ */
+export interface AgentRuntimeRequestHooks {
+    /** Call when a request arrives. */
+    onRequestStart(): void;
+    /**
+     * Call when the handler ends the response, before the response completes.
+     * Resolves once metrics are drained and spans and logs are flushed.
+     */
+    onRequestEnd(): Promise<void>;
+}
+/**
+ * Builds the request hooks that drive export for the given processors and
+ * readers on a runtime that throttles the CPU between requests.
+ *
+ * Each request start and end drives every request-driven metric reader in
+ * `otelHooks.metricReaders`. Each request end also force-flushes every span and
+ * log record processor in `otelHooks`. Other metric readers are left alone:
+ * flushing them would collect outside the request-driven reader's spacing
+ * rules.
+ *
+ * @experimental (Experimental, subject to change)
+ *
+ * @param otelHooks The processors and readers to drive, usually the result of
+ *     {@link getGcpExporters}.
+ */
+export declare function agentRuntimeRequestHooks(otelHooks: OTelHooks): AgentRuntimeRequestHooks;