@google/adk 2.4.0 → 2.5.0

package/dist/esm/workflow/node_runner.js

@@ -7,11 +7,11 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { context, SpanStatusCode, trace } from "@opentelemetry/api";
 import { InvocationContext } from "../agents/invocation_context.js";
 import { createEvent } from "../events/event.js";
-import { traceNodeExecution, tracer } from "../telemetry/tracing.js";
-import { formatError } from "../utils/error_utils.js";
+import {
+  recordNodeInvocation
+} from "../telemetry/api/instrumentation.js";
 import { createSubBranch } from "./branch_path.js";
 import {
   InvocationAbortedError,
@@ -31,11 +31,12 @@ function executeChildNode(params) {
   const { parent, node, options = {} } = params;
   const nodeName = (_a = options.nodeName) != null ? _a : node.name;
   const nodePath = (_b = options.overrideNodePath) != null ? _b : parent.nodePath ? `${parent.nodePath}.${nodeName}` : nodeName;
-  const span = tracer.startSpan(`execute_node ${nodeName}`);
-  return context.with(
-    trace.setSpan(context.active(), span),
-    () => runChildNode({ params, nodeName, nodePath, span })
-  );
+  const scope = recordNodeInvocation({
+    node,
+    nodeName,
+    sessionId: parent.invocationContext.session.id
+  });
+  return scope.run(() => runChildNode({ params, nodeName, nodePath, scope }));
 }
 __name(executeChildNode, "executeChildNode");
 async function runChildNode({
@@ -50,7 +51,7 @@ async function runChildNode({
   },
   nodeName,
   nodePath,
-  span
+  scope
 }) {
   var _a, _b, _c, _d;
   const runId = (_a = options.runId) != null ? _a : nodeName;
@@ -104,13 +105,6 @@ async function runChildNode({
       });
       if (skipOutput !== void 0) {
         child.output = skipOutput;
-        traceNodeExecution({
-          nodePath,
-          runId,
-          attempt: nodeState.attemptCount,
-          status: "completed",
-          interruptCount: child.interruptIds.length
-        });
         if (options.useAsOutput) {
           parent.output = child.output;
           parent.route = child.route;
@@ -124,16 +118,14 @@ async function runChildNode({
       resetState(child);
       child.attemptCount = nodeState.attemptCount;
       try {
-        inputRecorded = await runAttempt({
+        inputRecorded = await runOnce({
           node,
           child,
           input,
           nodeName,
           branch,
           isolationScope,
-          nodePath,
-          runId,
-          attempt: nodeState.attemptCount
+          scope
         });
         failIfNodeReportedError(child, nodeName);
         succeeded = true;
@@ -160,13 +152,6 @@ async function runChildNode({
     if (!inputRecorded && child.interruptIds.length > 0) {
       recordInputForResume({ child, nodeName, branch, isolationScope, input });
     }
-    traceNodeExecution({
-      nodePath,
-      runId,
-      attempt: nodeState.attemptCount,
-      status: child.interruptIds.length > 0 ? "waiting" : "completed",
-      interruptCount: child.interruptIds.length
-    });
     if (pluginManager == null ? void 0 : pluginManager.hasPlugins) {
       const replacedOutput = await pluginManager.runAfterNodeCallback({
         node,
@@ -184,58 +169,13 @@ async function runChildNode({
     }
     return child;
   } catch (err) {
-    traceNodeExecution({
-      nodePath,
-      runId,
-      attempt: nodeState.attemptCount,
-      status: "failed",
-      interruptCount: child.interruptIds.length
-    });
-    span.setStatus({ code: SpanStatusCode.ERROR, message: formatError(err) });
+    scope.end(err);
     throw err;
   } finally {
-    span.end();
+    scope.end();
   }
 }
 __name(runChildNode, "runChildNode");
-function runAttempt(params) {
-  const { node, nodePath, runId, attempt } = params;
-  if (!node.preparedRetryConfig) {
-    return runOnce(params);
-  }
-  return tracer.startActiveSpan(
-    `execute_node_attempt ${params.nodeName}`,
-    async (span) => {
-      try {
-        const inputRecorded = await runOnce(params);
-        traceNodeExecution({
-          nodePath,
-          runId,
-          attempt,
-          status: params.child.interruptIds.length > 0 ? "waiting" : "completed",
-          interruptCount: params.child.interruptIds.length
-        });
-        return inputRecorded;
-      } catch (err) {
-        traceNodeExecution({
-          nodePath,
-          runId,
-          attempt,
-          status: "failed",
-          interruptCount: params.child.interruptIds.length
-        });
-        span.setStatus({
-          code: SpanStatusCode.ERROR,
-          message: formatError(err)
-        });
-        throw err;
-      } finally {
-        span.end();
-      }
-    }
-  );
-}
-__name(runAttempt, "runAttempt");
 function failIfNodeReportedError(child, nodeName) {
   const reported = child.reportedError;
   if (!reported || child.output !== void 0 || child.route !== void 0 || child.interruptIds.length > 0) {
@@ -262,11 +202,12 @@ async function runOnce({
   input,
   nodeName,
   branch,
-  isolationScope
+  isolationScope,
+  scope
 }) {
   var _a;
   let inputRecorded = false;
-  const consume = /* @__PURE__ */ __name((event) => {
+  const consume = /* @__PURE__ */ __name(async (event) => {
     var _a2, _b, _c;
     enrichEvent({ event, child, nodeName, branch, isolationScope });
     const emittedDelta = (_a2 = event.actions) == null ? void 0 : _a2.stateDelta;
@@ -305,13 +246,18 @@ async function runOnce({
       };
       inputRecorded = true;
     }
-    child.channel.push(event);
+    scope.recordEvent(event);
+    if (event.partial) {
+      child.channel.push(event);
+    } else {
+      await child.channel.pushAndWait(event);
+    }
   }, "consume");
   const parentSignal = child.invocationContext.abortSignal;
   const hasTimeout = typeof node.timeout === "number" && node.timeout > 0;
   if (!hasTimeout && !parentSignal) {
     for await (const event of node.run(child, input)) {
-      consume(event);
+      await consume(event);
     }
     return inputRecorded;
   }
@@ -319,7 +265,7 @@ async function runOnce({
     child.abortSignal = parentSignal;
     try {
       for await (const event of node.run(child, input)) {
-        consume(event);
+        await consume(event);
       }
     } finally {
       child.abortSignal = void 0;
@@ -359,7 +305,7 @@ async function runOnce({
   try {
     let result = await Promise.race([iterator.next(), aborted]);
     while (!result.done) {
-      consume(result.value);
+      await Promise.race([consume(result.value), aborted]);
       result = await Promise.race([iterator.next(), aborted]);
     }
   } finally {

package/dist/esm/workflow/nodes/parallel_worker.js

@@ -7,14 +7,19 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+var _a, _b;
 import { BaseNode } from "../base_node.js";
 import { isNodeInterruptedError } from "../errors.js";
 import { buildNode } from "../utils/workflow_graph_utils.js";
 const DEFAULT_MAX_PARALLEL_WORKERS = 8;
-const _ParallelWorker = class _ParallelWorker extends BaseNode {
+const PARALLEL_WORKER_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "google.adk.workflow.parallelWorker"
+);
+const _ParallelWorker = class _ParallelWorker extends (_b = BaseNode, _a = PARALLEL_WORKER_SIGNATURE_SYMBOL, _b) {
   constructor(inner, config = {}) {
     const built = buildNode(inner);
     super({ name: built.name, rerunOnResume: true });
+    this[_a] = true;
     if (config.maxParallelWorkers !== void 0 && config.maxParallelWorkers < 1) {
       throw new Error("maxParallelWorkers must be greater than or equal to 1.");
     }
@@ -22,7 +27,7 @@ const _ParallelWorker = class _ParallelWorker extends BaseNode {
     this.maxParallelWorkers = config.maxParallelWorkers;
   }
   async *runImpl(ctx, input) {
-    var _a;
+    var _a2;
     const items = Array.isArray(input) ? input : [input];
     if (items.length === 0) {
       yield [];
@@ -30,7 +35,7 @@ const _ParallelWorker = class _ParallelWorker extends BaseNode {
     }
     const results = new Array(items.length);
     const poolSize = Math.min(
-      (_a = this.maxParallelWorkers) != null ? _a : DEFAULT_MAX_PARALLEL_WORKERS,
+      (_a2 = this.maxParallelWorkers) != null ? _a2 : DEFAULT_MAX_PARALLEL_WORKERS,
       items.length
     );
     let nextIndex = 0;
@@ -39,8 +44,8 @@ const _ParallelWorker = class _ParallelWorker extends BaseNode {
     let interrupted = false;
     const interruptIds = [];
     const isAborted = /* @__PURE__ */ __name(() => {
-      var _a2, _b;
-      return ((_a2 = ctx.abortSignal) == null ? void 0 : _a2.aborted) === true || ((_b = ctx.invocationContext.abortSignal) == null ? void 0 : _b.aborted) === true;
+      var _a3, _b2;
+      return ((_a3 = ctx.abortSignal) == null ? void 0 : _a3.aborted) === true || ((_b2 = ctx.invocationContext.abortSignal) == null ? void 0 : _b2.aborted) === true;
     }, "isAborted");
     const worker = /* @__PURE__ */ __name(async () => {
       while (!failed && !interrupted && !isAborted()) {
@@ -97,6 +102,11 @@ const _ParallelWorker = class _ParallelWorker extends BaseNode {
 };
 __name(_ParallelWorker, "ParallelWorker");
 let ParallelWorker = _ParallelWorker;
+function isParallelWorker(value) {
+  return typeof value === "object" && value !== null && PARALLEL_WORKER_SIGNATURE_SYMBOL in value && value[PARALLEL_WORKER_SIGNATURE_SYMBOL] === true;
+}
+__name(isParallelWorker, "isParallelWorker");
 export {
-  ParallelWorker
+  ParallelWorker,
+  isParallelWorker
 };

package/dist/esm/workflow/run_llm_agent_as_node.js

@@ -23,9 +23,7 @@ async function* runLlmAgentAsNode(agent, ctx, nodeInput) {
   if (!isTaskMode && !agent.includeContentsExplicit) {
     agent.includeContents = "none";
   }
-  if (!isTaskMode) {
-    await appendNodeInputAsUserTurn(ctx, nodeInput);
-  }
+  const inputEvent = isTaskMode ? void 0 : pushNodeInputAsUserTurn(ctx, nodeInput);
   const agentIc = withWorkflowInstructionScope(ctx.getInvocationContext(), {
     input: nodeInput,
     outputsByNode: collectPredecessorOutputs(ctx)
@@ -34,15 +32,19 @@ async function* runLlmAgentAsNode(agent, ctx, nodeInput) {
     yield* runTaskMode(ctx, agentIc, agent);
     return;
   }
-  for await (const event of agent.runAsync(agentIc)) {
-    maybeSetOutput(agent, event);
-    yield event;
+  try {
+    for await (const event of agent.runAsync(agentIc)) {
+      maybeSetOutput(agent, event);
+      yield event;
+    }
+  } finally {
+    removeEvent(ctx.session.events, inputEvent);
   }
 }
 __name(runLlmAgentAsNode, "runLlmAgentAsNode");
-async function appendNodeInputAsUserTurn(ctx, nodeInput) {
+function pushNodeInputAsUserTurn(ctx, nodeInput) {
   if (nodeInput === void 0 || nodeInput === null) {
-    return;
+    return void 0;
   }
   const userEvent = createEvent({
     author: "user",
@@ -53,14 +55,17 @@ async function appendNodeInputAsUserTurn(ctx, nodeInput) {
   if (ctx.isolationScope !== void 0) {
     userEvent.isolationScope = ctx.isolationScope;
   }
-  const sessionService = ctx.invocationContext.sessionService;
-  if (sessionService) {
-    await sessionService.appendEvent({ session: ctx.session, event: userEvent });
-  } else {
-    ctx.session.events.push(userEvent);
+  ctx.session.events.push(userEvent);
+  return userEvent;
+}
+__name(pushNodeInputAsUserTurn, "pushNodeInputAsUserTurn");
+function removeEvent(events, event) {
+  const index = event ? events.indexOf(event) : -1;
+  if (index !== -1) {
+    events.splice(index, 1);
   }
 }
-__name(appendNodeInputAsUserTurn, "appendNodeInputAsUserTurn");
+__name(removeEvent, "removeEvent");
 async function* runTaskMode(ctx, agentIc, agent) {
   var _a, _b;
   const finishTool = agent.finishTaskTool;

package/dist/esm/workflow/utils/retry_utils.js

@@ -13,7 +13,7 @@ const DEFAULT_MAX_DELAY_SECONDS = 60;
 const DEFAULT_BACKOFF_FACTOR = 2;
 const DEFAULT_JITTER = 1;
 function errorNames(error) {
-  var _a;
+  var _a, _b, _c;
   if (error instanceof Error) {
     const names = [(_a = error.constructor) == null ? void 0 : _a.name, error.name].filter(
       (name) => !!name
@@ -21,7 +21,7 @@ function errorNames(error) {
     return [...new Set(names)];
   }
   if (typeof error === "object" && error !== null) {
-    return [error.constructor.name];
+    return [(_c = (_b = error.constructor) == null ? void 0 : _b.name) != null ? _c : "Object"];
   }
   return [typeof error];
 }

package/dist/esm/workflow/workflow.js

@@ -17,8 +17,7 @@ var __decorateClass = (decorators, target, key, kind) => {
  * SPDX-License-Identifier: Apache-2.0
  */
 var _a, _b;
-import { context, trace } from "@opentelemetry/api";
-import { tracer, traceWorkflowInvocation } from "../telemetry/tracing.js";
+import { recordWorkflowInvocation } from "../telemetry/api/instrumentation.js";
 import { experimental } from "../utils/experimental.js";
 import { BaseNode } from "./base_node.js";
 import { commonPrefixOf } from "./branch_path.js";
@@ -96,19 +95,20 @@ let Workflow = class extends (_b = BaseNode, _a = WORKFLOW_SIGNATURE_SYMBOL, _b)
       dynamicState,
       abort.controller.signal
     );
-    const span = tracer.startSpan(`invoke_workflow ${this.name}`);
+    const telemetryScope = recordWorkflowInvocation({
+      workflow: this,
+      sessionId: ctx.invocationContext.session.id
+    });
     try {
-      await context.with(trace.setSpan(context.active(), span), () => {
-        traceWorkflowInvocation({
-          workflowName: this.name,
-          nodePath: ctx.nodePath,
-          sessionId: ctx.invocationContext.session.id
-        });
-        return this.orchestrate(ctx, nodeInput, dynamicState, abort.controller);
-      });
+      await telemetryScope.run(
+        () => this.orchestrate(ctx, nodeInput, dynamicState, abort.controller)
+      );
+    } catch (error) {
+      telemetryScope.end(error);
+      throw error;
     } finally {
       abort.dispose();
-      span.end();
+      telemetryScope.end();
     }
   }
   /**

package/dist/types/a2a/a2a_remote_agent.d.ts

@@ -56,10 +56,16 @@ export interface RemoteA2AAgentConfig extends BaseAgentConfig {
     resolveAgentCardOptions?: ResolveAgentCardOptions;
     /**
      * Optional pre-initialized Client for connection pooling.
+     *
+     * A provided client sends requests as it is configured, so the default
+     * trace context propagation does not apply to it.
      */
     client?: Client;
     /**
      * Optional ClientFactory for creating the A2A Client.
+     *
+     * Clients from a provided factory send requests as it is configured, so the
+     * default trace context propagation does not apply to them.
      */
     clientFactory?: ClientFactory;
     /**

package/dist/types/a2a/a2a_remote_agent_utils.d.ts

@@ -15,14 +15,15 @@ export interface UserFunctionCall {
 }
 /**
  * Returns a UserFunctionCall when the event at `index` contains a
- * FunctionResponse that can be traced back to a preceding FunctionCall event.
+ * FunctionResponse that can be traced back to this agent's FunctionCall event.
  *
  * @param session - The session whose event history to inspect.
  * @param index - Index of the candidate event to examine.
+ * @param agentName - The remote agent whose pending task to resume.
  * @returns The matching `UserFunctionCall`, or `undefined` if the event at
  *   `index` is not a user function-response event or has no preceding call.
  */
-export declare function getUserFunctionCallAt(session: Session, index: number): UserFunctionCall | undefined;
+export declare function getUserFunctionCallAt(session: Session, index: number, agentName: string): UserFunctionCall | undefined;
 /**
  * Checks if an event contains a function call with the given ID.
  *

package/dist/types/agents/agent_engine_client.d.ts

@@ -3,35 +3,153 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+/** Identifies the deployed Agent Engine that an {@link AgentEngineClient} calls. */
 export interface AgentEngineConfig {
     project: string;
     location: string;
     reasoningEngineId: string;
+    /**
+     * Overrides the API endpoint. By default the endpoint is resolved from
+     * `location`, and `global` resolves to `aiplatform.googleapis.com`.
+     */
+    apiEndpoint?: string;
 }
+/**
+ * Arguments for a session operation on a deployed Agent Engine.
+ *
+ * The client sends `userId`, `sessionId` and `expireTime` as `user_id`,
+ * `session_id` and `expire_time`, which are the argument names the remote
+ * methods read. When both spellings are given, the snake_case value wins.
+ * Other keys are sent unchanged.
+ */
 export interface SessionConfig {
     userId?: string;
+    user_id?: string;
     sessionId?: string;
+    session_id?: string;
+    state?: Record<string, unknown>;
+    ttl?: string;
+    expireTime?: string;
+    expire_time?: string;
+    appName?: string;
+    app_name?: string;
+    /**
+     * Overrides the remote class method that the client calls. The client sends
+     * it on the request itself, never inside `input`.
+     */
+    classMethod?: string;
+    [key: string]: unknown;
 }
+/**
+ * Arguments for {@link AgentEngineClient.query} and
+ * {@link AgentEngineClient.streamQuery}.
+ *
+ * The client sends `runConfig` and `stateDelta` as `run_config` and
+ * `state_delta`, in addition to the renames that {@link SessionConfig}
+ * describes.
+ */
 export interface QueryConfig extends SessionConfig {
     message: unknown;
+    /**
+     * The run configuration for the remote agent. The client renames only this
+     * top-level key and sends the contents unchanged. Use the field names that
+     * the remote engine expects, for example `max_llm_calls` for a Python
+     * engine.
+     */
+    runConfig?: Record<string, unknown>;
+    /** The same as {@link QueryConfig.runConfig}. When both are given, this wins. */
+    run_config?: Record<string, unknown>;
     [key: string]: unknown;
 }
+/** Arguments for {@link AgentEngineClient.getSession}. */
+export type GetSessionConfig = SessionConfig;
+/** Arguments for {@link AgentEngineClient.listSessions}. */
+export type ListSessionsConfig = SessionConfig;
+/** Arguments for {@link AgentEngineClient.deleteSession}. */
+export type DeleteSessionConfig = SessionConfig;
+/** Thrown when a call to a deployed Agent Engine fails. */
 export declare class AgentExecutionError extends Error {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
 }
+/**
+ * Calls an agent deployed to Vertex AI Agent Engine.
+ *
+ * The client loads the optional peer dependency `@google-cloud/aiplatform` on
+ * its first call, not when it is constructed. Call
+ * {@link AgentEngineClient.close} to release
+ * the underlying gRPC channel.
+ */
 export declare class AgentEngineClient {
-    private client;
-    private reasoningEnginePath;
+    private readonly apiEndpoint;
+    private readonly reasoningEnginePath;
+    private clientPromise?;
     constructor(config: AgentEngineConfig);
     /**
      * Creates a remote session.
      *
-     * @returns The `create_session` payload returned by the Agent Engine. When
+     * Calls the `async_create_session` class method unless `config.classMethod`
+     * names another one.
+     *
+     * @returns The session payload returned by the Agent Engine. When
      *     `config.sessionId` is omitted the engine generates one, and this is the
      *     only place the caller can read it back from.
      */
     createSession(config: SessionConfig): Promise<unknown>;
+    /**
+     * Reads a remote session.
+     *
+     * Calls the `async_get_session` class method unless `config.classMethod`
+     * names another one.
+     *
+     * @throws {@link AgentExecutionError} if the user id or the session id is
+     *     missing, or if the call fails.
+     */
+    getSession(config: GetSessionConfig): Promise<unknown>;
+    /**
+     * Lists the remote sessions of a user.
+     *
+     * Calls the `async_list_sessions` class method unless `config.classMethod`
+     * names another one.
+     */
+    listSessions(config: ListSessionsConfig): Promise<unknown>;
+    /**
+     * Deletes a remote session.
+     *
+     * Calls the `async_delete_session` class method unless `config.classMethod`
+     * names another one.
+     */
+    deleteSession(config: DeleteSessionConfig): Promise<void>;
+    /**
+     * Sends a query and waits for the whole response.
+     *
+     * Calls the `query` class method unless `config.classMethod` names another
+     * one.
+     */
     query(config: QueryConfig): Promise<unknown>;
+    /**
+     * Sends a query and yields each streamed response value.
+     *
+     * Calls the `async_stream_query` class method unless `config.classMethod`
+     * names another one. The stream can be server-sent events or
+     * newline-delimited JSON.
+     */
     streamQuery(config: QueryConfig): AsyncGenerator<unknown, void, unknown>;
+    /**
+     * Closes the underlying gRPC client.
+     *
+     * Does nothing if no call has created the client yet, and is safe to call
+     * more than once. A later call creates a new client.
+     */
+    close(): Promise<void>;
+    private callQueryMethod;
+    /**
+     * Resolves the SDK helpers and the gRPC client, loading the optional peer on
+     * first use.
+     *
+     * A created client is kept. A failure is not kept, so the next call tries
+     * again, for example once the peer is installed.
+     */
+    private getClient;
+    private createClient;
 }

package/dist/types/agents/base_agent.d.ts

@@ -187,6 +187,8 @@ export declare abstract class BaseAgent<TConfig extends BaseAgentConfig = BaseAg
      * @returns An AsyncGenerator that yields the events generated by the agent.
      */
     runLive(parentContext: InvocationContext): AsyncGenerator<Event, void, void>;
+    /** Reports execution failures without replacing the original thrown value. */
+    private handleAgentErrorCallback;
     /**
      * Core logic to run this agent via text-based conversation.
      *

package/dist/types/agents/processors/content_processor_utils.d.ts

@@ -16,11 +16,11 @@ export declare function removeClientFunctionCallId(content: Content): void;
 /**
  * Get the contents for the LLM request.
  *
- * @param events: A list of all session events.
- * @param agentName: The name of the agent.
- * @param currentBranch: The current branch of the agent.
- * @param currentIsolationScope: The isolation scope of the current node, if any.
- * @param preserveFunctionCallIds: Whether to preserve client-generated
+ * @param events A list of all session events.
+ * @param agentName The name of the agent.
+ * @param currentBranch The current branch of the agent.
+ * @param currentIsolationScope The isolation scope of the current node, if any.
+ * @param preserveFunctionCallIds Whether to preserve client-generated
  *     `adk-*` function call and response IDs instead of stripping them.
  *
  * @returns A list of processed contents.
@@ -37,9 +37,9 @@ export declare function getContents(events: Event[], agentName: string, currentB
  * In multi-agent scenarios, the "current turn" for an agent starts from an
  * actual user or from another agent.
  *
- * @param events: A list of all session events.
- * @param agentName: The name of the agent.
- * @param currentBranch: The current branch of the agent.
+ * @param events A list of all session events.
+ * @param agentName The name of the agent.
+ * @param currentBranch The current branch of the agent.
  *
  * @returns A list of contents for the current turn only, preserving context
  *     needed for proper tool execution while excluding conversation history.
@@ -52,7 +52,7 @@ export declare function getCurrentTurnContents(events: Event[], agentName: strin
  *  1. function_call and function_response are always of the same number.
  *  2. The function_call and function_response are consecutively in the content.
  *
- * @param events: A list of function_response events.
+ * @param events A list of function_response events.
  *
  * NOTE:
  * function_response_events must fulfill these requirements:

package/dist/types/agents/run_config.d.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { AudioTranscriptionConfig, ContextWindowCompressionConfig, Modality, ProactivityConfig, RealtimeInputConfig, SpeechConfig } from '@google/genai';
+import type { TelemetryConfig } from '../telemetry/api/instrumentation.js';
 /**
  * The streaming mode for the run config.
  */
@@ -123,6 +124,18 @@ export interface RunConfig {
      * option does not exist there.
      */
     allowRemoteToolConfirmation?: boolean;
+    /**
+     * Telemetry overrides for this run.
+     *
+     * Each field set here replaces its environment variable for the spans, log
+     * records and metrics of this run only; a field left unset falls back to the
+     * environment. An operator can make the environment win over every run by
+     * setting `ADK_TELEMETRY_IGNORE_RUN_CONFIG` to `true` or `1`.
+     *
+     * WARNING: This feature is **experimental** and its API or behavior may
+     * change in future releases.
+     */
+    telemetry?: TelemetryConfig;
     /**
      * Set by the A2A executor to record that this run's message came from a
      * remote peer. Not part of the configuration surface: an application setting
@@ -173,5 +186,6 @@ export declare function createRunConfig(params?: Partial<RunConfig>): {
     plainTextToolConfirmation?: boolean | undefined;
     a2aMetadata?: Record<string, unknown> | undefined;
     allowRemoteToolConfirmation?: boolean | undefined;
+    telemetry?: TelemetryConfig | undefined;
     remoteDelivered?: boolean | undefined;
 };