@livekit/agents 1.0.17 → 1.0.19

package/src/telemetry/traces.ts

@@ -0,0 +1,266 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import {
+  type Attributes,
+  type Context,
+  type Span,
+  type SpanOptions,
+  type Tracer,
+  type TracerProvider,
+  context as otelContext,
+  trace,
+} from '@opentelemetry/api';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { CompressionAlgorithm } from '@opentelemetry/otlp-exporter-base';
+import { Resource } from '@opentelemetry/resources';
+import type { ReadableSpan, SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import { AccessToken } from 'livekit-server-sdk';
+
+export interface StartSpanOptions {
+  /** Name of the span */
+  name: string;
+  /** Optional parent context to use for this span */
+  context?: Context;
+  /** Attributes to set on the span when it starts */
+  attributes?: Attributes;
+  /** Whether to end the span when the function exits (default: true) */
+  endOnExit?: boolean;
+}
+
+/**
+ * A dynamic tracer that allows the tracer provider to be changed at runtime.
+ */
+class DynamicTracer {
+  private tracerProvider: TracerProvider;
+  private tracer: Tracer;
+  private readonly instrumentingModuleName: string;
+
+  constructor(instrumentingModuleName: string) {
+    this.instrumentingModuleName = instrumentingModuleName;
+    this.tracerProvider = trace.getTracerProvider();
+    this.tracer = trace.getTracer(instrumentingModuleName);
+  }
+
+  /**
+   * Set a new tracer provider. This updates the underlying tracer instance.
+   * @param provider - The new tracer provider to use
+   */
+  setProvider(provider: TracerProvider): void {
+    this.tracerProvider = provider;
+    this.tracer = this.tracerProvider.getTracer(this.instrumentingModuleName);
+  }
+
+  /**
+   * Get the underlying OpenTelemetry tracer.
+   * Use this to access the full Tracer API when needed.
+   */
+  getTracer(): Tracer {
+    return this.tracer;
+  }
+
+  /**
+   * Start a span manually (without making it active).
+   * You must call span.end() when done.
+   *
+   * @param options - Span configuration including name
+   * @returns The created span
+   */
+  startSpan(options: StartSpanOptions): Span {
+    const ctx = options.context || otelContext.active();
+    const span = this.tracer.startSpan(
+      options.name,
+      {
+        attributes: options.attributes,
+      },
+      ctx,
+    );
+
+    return span;
+  }
+
+  /**
+   * Start a new span and make it active in the current context.
+   * The span will automatically be ended when the provided function completes (unless endOnExit=false).
+   *
+   * @param fn - The function to execute within the span context
+   * @param options - Span configuration including name
+   * @returns The result of the provided function
+   */
+  async startActiveSpan<T>(fn: (span: Span) => Promise<T>, options: StartSpanOptions): Promise<T> {
+    const ctx = options.context || otelContext.active();
+    const endOnExit = options.endOnExit === undefined ? true : options.endOnExit; // default true
+    const opts: SpanOptions = { attributes: options.attributes };
+
+    return new Promise((resolve, reject) => {
+      this.tracer.startActiveSpan(options.name, opts, ctx, async (span) => {
+        try {
+          const result = await fn(span);
+          resolve(result);
+        } catch (error) {
+          reject(error);
+        } finally {
+          if (endOnExit) {
+            span.end();
+          }
+        }
+      });
+    });
+  }
+
+  /**
+   * Synchronous version of startActiveSpan for non-async operations.
+   *
+   * @param fn - The function to execute within the span context
+   * @param options - Span configuration including name
+   * @returns The result of the provided function
+   */
+  startActiveSpanSync<T>(fn: (span: Span) => T, options: StartSpanOptions): T {
+    const ctx = options.context || otelContext.active();
+    const endOnExit = options.endOnExit === undefined ? true : options.endOnExit; // default true
+    const opts: SpanOptions = { attributes: options.attributes };
+
+    return this.tracer.startActiveSpan(options.name, opts, ctx, (span) => {
+      try {
+        return fn(span);
+      } finally {
+        if (endOnExit) {
+          span.end();
+        }
+      }
+    });
+  }
+}
+
+/**
+ * The global tracer instance used throughout the agents framework.
+ * This tracer can have its provider updated at runtime via setTracerProvider().
+ */
+export const tracer = new DynamicTracer('livekit-agents');
+
+class MetadataSpanProcessor implements SpanProcessor {
+  private metadata: Attributes;
+
+  constructor(metadata: Attributes) {
+    this.metadata = metadata;
+  }
+
+  onStart(span: Span, _parentContext: Context): void {
+    span.setAttributes(this.metadata);
+  }
+
+  onEnd(_span: ReadableSpan): void {}
+
+  shutdown(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  forceFlush(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+// TODO(brian): PR4 - Add MetadataLogProcessor for structured logging
+
+// TODO(brian): PR4 - Add ExtraDetailsProcessor for structured logging
+
+/**
+ * Set the tracer provider for the livekit-agents framework.
+ * This should be called before agent session start if using custom tracer providers.
+ *
+ * @param provider - The tracer provider to use (must be a NodeTracerProvider)
+ * @param options - Optional configuration with metadata property to inject into all spans
+ *
+ * @example
+ * ```typescript
+ * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ * import { setTracerProvider } from '@livekit/agents/telemetry';
+ *
+ * const provider = new NodeTracerProvider();
+ * setTracerProvider(provider, {
+ *   metadata: { room_id: 'room123', job_id: 'job456' }
+ * });
+ * ```
+ */
+export function setTracerProvider(
+  provider: NodeTracerProvider,
+  options?: { metadata?: Attributes },
+): void {
+  if (options?.metadata) {
+    provider.addSpanProcessor(new MetadataSpanProcessor(options.metadata));
+  }
+
+  tracer.setProvider(provider);
+}
+
+/**
+ * Setup OpenTelemetry tracer for LiveKit Cloud observability.
+ * This configures OTLP exporters to send traces to LiveKit Cloud.
+ *
+ * @param options - Configuration for cloud tracer with roomId, jobId, and cloudHostname properties
+ *
+ * @internal
+ */
+export async function setupCloudTracer(options: {
+  roomId: string;
+  jobId: string;
+  cloudHostname: string;
+}): Promise<void> {
+  const { roomId, jobId, cloudHostname } = options;
+
+  const apiKey = process.env.LIVEKIT_API_KEY;
+  const apiSecret = process.env.LIVEKIT_API_SECRET;
+
+  if (!apiKey || !apiSecret) {
+    throw new Error('LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set for cloud tracing');
+  }
+
+  const token = new AccessToken(apiKey, apiSecret, {
+    identity: 'livekit-agents-telemetry',
+    ttl: '6h',
+  });
+  token.addObservabilityGrant({ write: true });
+
+  try {
+    const jwt = await token.toJwt();
+
+    const headers = {
+      Authorization: `Bearer ${jwt}`,
+    };
+
+    const metadata: Attributes = {
+      room_id: roomId,
+      job_id: jobId,
+    };
+
+    const resource = new Resource({
+      [ATTR_SERVICE_NAME]: 'livekit-agents',
+      room_id: roomId,
+      job_id: jobId,
+    });
+
+    // Configure OTLP exporter to send traces to LiveKit Cloud
+    const spanExporter = new OTLPTraceExporter({
+      url: `https://${cloudHostname}/observability/traces/otlp/v0`,
+      headers,
+      compression: CompressionAlgorithm.GZIP,
+    });
+
+    const tracerProvider = new NodeTracerProvider({
+      resource,
+      spanProcessors: [new MetadataSpanProcessor(metadata), new BatchSpanProcessor(spanExporter)],
+    });
+    tracerProvider.register();
+
+    // Metadata processor is already configured in the constructor above
+    setTracerProvider(tracerProvider);
+
+    // TODO(brian): PR4 - Add logger provider setup here for structured logging
+    // Similar to Python's setup: LoggerProvider, OTLPLogExporter, BatchLogRecordProcessor
+  } catch (error) {
+    console.error('Failed to setup cloud tracer:', error);
+    throw error;
+  }
+}

package/src/telemetry/utils.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { type Span, SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api';
+import type { RealtimeModelMetrics } from '../metrics/base.js';
+import * as traceTypes from './trace_types.js';
+import { tracer } from './traces.js';
+
+export function recordException(span: Span, error: Error): void {
+  span.recordException(error);
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error.message,
+  });
+
+  // Set exception attributes for better visibility
+  // (in case the exception event is not rendered by the backend)
+  span.setAttributes({
+    [traceTypes.ATTR_EXCEPTION_TYPE]: error.constructor.name,
+    [traceTypes.ATTR_EXCEPTION_MESSAGE]: error.message,
+    [traceTypes.ATTR_EXCEPTION_TRACE]: error.stack || '',
+  });
+}
+
+export function recordRealtimeMetrics(span: Span, metrics: RealtimeModelMetrics): void {
+  const attrs: Record<string, string | number> = {
+    [traceTypes.ATTR_GEN_AI_REQUEST_MODEL]: metrics.label || 'unknown',
+    [traceTypes.ATTR_REALTIME_MODEL_METRICS]: JSON.stringify(metrics),
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TOKENS]: metrics.inputTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TOKENS]: metrics.outputTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TEXT_TOKENS]: metrics.inputTokenDetails.textTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_AUDIO_TOKENS]: metrics.inputTokenDetails.audioTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_CACHED_TOKENS]: metrics.inputTokenDetails.cachedTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TEXT_TOKENS]: metrics.outputTokenDetails.textTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_AUDIO_TOKENS]: metrics.outputTokenDetails.audioTokens,
+  };
+
+  // Add LangFuse-specific completion start time if TTFT is available
+  if (metrics.ttftMs !== undefined && metrics.ttftMs !== -1) {
+    const completionStartTime = metrics.timestamp + metrics.ttftMs;
+    // Convert to UTC ISO string for LangFuse compatibility
+    const completionStartTimeUtc = new Date(completionStartTime).toISOString();
+    attrs[traceTypes.ATTR_LANGFUSE_COMPLETION_START_TIME] = completionStartTimeUtc;
+  }
+
+  if (span.isRecording()) {
+    span.setAttributes(attrs);
+  } else {
+    const currentContext = otelContext.active();
+    const spanContext = trace.setSpan(currentContext, span);
+
+    // Create a dedicated child span for orphaned metrics
+    tracer.getTracer().startActiveSpan('realtime_metrics', {}, spanContext, (child) => {
+      try {
+        child.setAttributes(attrs);
+      } finally {
+        child.end();
+      }
+    });
+  }
+}

package/src/tts/tts.ts

@@ -157,8 +157,10 @@ export abstract class SynthesizeStream
   }
 
   private async mainTask() {
+    // TODO(brian): PR3 - Add span wrapping: tracer.startActiveSpan('tts_request', ..., { endOnExit: false })
     for (let i = 0; i < this._connOptions.maxRetry + 1; i++) {
       try {
+        // TODO(brian): PR3 - Add span for retry attempts: tracer.startActiveSpan('tts_request_run', ...)
         return await this.run();
       } catch (error) {
         if (error instanceof APIError) {
@@ -385,8 +387,10 @@ export abstract class ChunkedStream implements AsyncIterableIterator<Synthesized
   }
 
   private async mainTask() {
+    // TODO(brian): PR3 - Add span wrapping: tracer.startActiveSpan('tts_request', ..., { endOnExit: false })
     for (let i = 0; i < this._connOptions.maxRetry + 1; i++) {
       try {
+        // TODO(brian): PR3 - Add span for retry attempts: tracer.startActiveSpan('tts_request_run', ...)
         return await this.run();
       } catch (error) {
         if (error instanceof APIError) {

package/src/utils.ts

@@ -15,6 +15,23 @@ import { TransformStream, type TransformStreamDefaultController } from 'node:str
 import { v4 as uuidv4 } from 'uuid';
 import { log } from './log.js';
 
+/**
+ * Recursively expands all nested properties of a type,
+ * resolving aliases so as to inspect the real shape in IDE.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type Expand<T> = T extends Function
+  ? T
+  : T extends object
+    ? T extends Array<infer U>
+      ? Array<Expand<U>>
+      : T extends Map<infer K, infer V>
+        ? Map<Expand<K>, Expand<V>>
+        : T extends Set<infer M>
+          ? Set<Expand<M>>
+          : { [K in keyof T]: Expand<T[K]> }
+    : T;
+
 /** Union of a single and a list of {@link AudioFrame}s */
 export type AudioBuffer = AudioFrame[] | AudioFrame;
 

package/src/voice/agent.ts

@@ -59,6 +59,7 @@ export interface ModelSettings {
 }
 
 export interface AgentOptions<UserData> {
+  id?: string;
   instructions: string;
   chatCtx?: ChatContext;
   tools?: ToolContext<UserData>;
@@ -72,6 +73,7 @@ export interface AgentOptions<UserData> {
 }
 
 export class Agent<UserData = any> {
+  private _id: string;
   private turnDetection?: TurnDetectionMode;
   private _stt?: STT;
   private _vad?: VAD;
@@ -91,6 +93,7 @@ export class Agent<UserData = any> {
   _tools?: ToolContext<UserData>;
 
   constructor({
+    id,
     instructions,
     chatCtx,
     tools,
@@ -100,6 +103,21 @@ export class Agent<UserData = any> {
     llm,
     tts,
   }: AgentOptions<UserData>) {
+    if (id) {
+      this._id = id;
+    } else {
+      // Convert class name to snake_case
+      const className = this.constructor.name;
+      if (className === 'Agent') {
+        this._id = 'default_agent';
+      } else {
+        this._id = className
+          .replace(/([A-Z])/g, '_$1')
+          .toLowerCase()
+          .replace(/^_/, '');
+      }
+    }
+
     this._instructions = instructions;
     this._tools = { ...tools };
     this._chatCtx = chatCtx
@@ -152,6 +170,10 @@ export class Agent<UserData = any> {
     return new ReadonlyChatContext(this._chatCtx.items);
   }
 
+  get id(): string {
+    return this._id;
+  }
+
   get instructions(): string {
     return this._instructions;
   }

package/src/voice/agent_activity.ts

@@ -202,6 +202,8 @@ export class AgentActivity implements RecognitionHooks {
   }
 
   async start(): Promise<void> {
+    // TODO(brian): PR3 - Add span: startSpan = tracer.startSpan('start_agent_activity', { attributes: { 'lk.agent_label': this.agent.label } })
+    // TODO(brian): PR3 - Wrap prewarm calls with trace.useSpan(startSpan, endOnExit: false)
     const unlock = await this.lock.lock();
     try {
       this.agent._agentActivity = this;
@@ -235,6 +237,14 @@ export class AgentActivity implements RecognitionHooks {
         } catch (error) {
           this.logger.error(error, 'failed to update the tools');
         }
+
+        if (!this.llm.capabilities.audioOutput && !this.tts && this.agentSession.output.audio) {
+          this.logger.error(
+            'audio output is enabled but RealtimeModel has no audio modality ' +
+              'and no TTS is set. Either enable audio modality in the RealtimeModel ' +
+              'or set a TTS model.',
+          );
+        }
       } else if (this.llm instanceof LLM) {
         try {
           updateInstructions({
@@ -281,6 +291,7 @@ export class AgentActivity implements RecognitionHooks {
       this.started = true;
 
       this._mainTask = Task.from(({ signal }) => this.mainTask(signal));
+      // TODO(brian): PR3 - Wrap onEnter with tracer.startActiveSpan('on_enter', { attributes: { 'lk.agent_label': this.agent.label }, context: startSpan context })
       this.createSpeechTask({
         task: Task.from(() => this.agent.onEnter()),
         name: 'AgentActivity_onEnter',
@@ -625,11 +636,21 @@ export class AgentActivity implements RecognitionHooks {
       return;
     }
 
+    // Refactored interruption word count check:
+    // - Always apply minInterruptionWords filtering when STT is available and minInterruptionWords > 0
+    // - Apply check to all STT results: empty string, undefined, or any length
+    // - This ensures consistent behavior across all interruption scenarios
     if (this.stt && this.agentSession.options.minInterruptionWords > 0 && this.audioRecognition) {
       const text = this.audioRecognition.currentTranscript;
-
       // TODO(shubhra): better word splitting for multi-language
-      if (text && splitWords(text, true).length < this.agentSession.options.minInterruptionWords) {
+
+      // Normalize text: convert undefined/null to empty string for consistent word counting
+      const normalizedText = text ?? '';
+      const wordCount = splitWords(normalizedText, true).length;
+
+      // Only allow interruption if word count meets or exceeds minInterruptionWords
+      // This applies to all cases: empty strings, partial speech, and full speech
+      if (wordCount < this.agentSession.options.minInterruptionWords) {
         return;
       }
     }
@@ -767,19 +788,30 @@ export class AgentActivity implements RecognitionHooks {
       return true;
     }
 
+    // Refactored interruption word count check for consistency with onVADInferenceDone:
+    // - Always apply minInterruptionWords filtering when STT is available and minInterruptionWords > 0
+    // - Use consistent word splitting logic with splitWords (matching onVADInferenceDone pattern)
     if (
       this.stt &&
       this.turnDetection !== 'manual' &&
       this._currentSpeech &&
       this._currentSpeech.allowInterruptions &&
       !this._currentSpeech.interrupted &&
-      this.agentSession.options.minInterruptionWords > 0 &&
-      info.newTranscript.split(' ').length < this.agentSession.options.minInterruptionWords
+      this.agentSession.options.minInterruptionWords > 0
     ) {
-      // avoid interruption if the new_transcript is too short
-      this.cancelPreemptiveGeneration();
-      this.logger.info('skipping user input, new_transcript is too short');
-      return false;
+      const wordCount = splitWords(info.newTranscript, true).length;
+      if (wordCount < this.agentSession.options.minInterruptionWords) {
+        // avoid interruption if the new_transcript contains fewer words than minInterruptionWords
+        this.cancelPreemptiveGeneration();
+        this.logger.info(
+          {
+            wordCount,
+            minInterruptionWords: this.agentSession.options.minInterruptionWords,
+          },
+          'skipping user input, word count below minimum interruption threshold',
+        );
+        return false;
+      }
     }
 
     const oldTask = this._userTurnCompletedTask;
@@ -1222,6 +1254,7 @@ export class AgentActivity implements RecognitionHooks {
     }
   }
 
+  // TODO(brian): PR3 - Wrap entire pipelineReplyTask() method with tracer.startActiveSpan('agent_turn')
   private async pipelineReplyTask(
     speechHandle: SpeechHandle,
     chatCtx: ChatContext,
@@ -1612,7 +1645,7 @@ export class AgentActivity implements RecognitionHooks {
 
     const readMessages = async (
       abortController: AbortController,
-      outputs: Array<[string, _TextOut | null, _AudioOut | null]>,
+      outputs: Array<[string, _TextOut | null, _AudioOut | null, ('text' | 'audio')[] | undefined]>,
     ) => {
       replyAbortController.signal.addEventListener('abort', () => abortController.abort(), {
         once: true,
@@ -1627,7 +1660,25 @@ export class AgentActivity implements RecognitionHooks {
             );
             break;
           }
-          const trNodeResult = await this.agent.transcriptionNode(msg.textStream, modelSettings);
+
+          const msgModalities = msg.modalities ? await msg.modalities : undefined;
+          let ttsTextInput: ReadableStream<string> | null = null;
+          let trTextInput: ReadableStream<string>;
+
+          if (msgModalities && !msgModalities.includes('audio') && this.tts) {
+            if (this.llm instanceof RealtimeModel && this.llm.capabilities.audioOutput) {
+              this.logger.warn(
+                'text response received from realtime API, falling back to use a TTS model.',
+              );
+            }
+            const [_ttsTextInput, _trTextInput] = msg.textStream.tee();
+            ttsTextInput = _ttsTextInput;
+            trTextInput = _trTextInput;
+          } else {
+            trTextInput = msg.textStream;
+          }
+
+          const trNodeResult = await this.agent.transcriptionNode(trTextInput, modelSettings);
           let textOut: _TextOut | null = null;
           if (trNodeResult) {
             const [textForwardTask, _textOut] = performTextForwarding(
@@ -1638,30 +1689,51 @@ export class AgentActivity implements RecognitionHooks {
             forwardTasks.push(textForwardTask);
             textOut = _textOut;
           }
+
           let audioOut: _AudioOut | null = null;
           if (audioOutput) {
-            const realtimeAudio = await this.agent.realtimeAudioOutputNode(
-              msg.audioStream,
-              modelSettings,
-            );
-            if (realtimeAudio) {
+            let realtimeAudioResult: ReadableStream<AudioFrame> | null = null;
+
+            if (ttsTextInput) {
+              const [ttsTask, ttsStream] = performTTSInference(
+                (...args) => this.agent.ttsNode(...args),
+                ttsTextInput,
+                modelSettings,
+                abortController,
+              );
+              tasks.push(ttsTask);
+              realtimeAudioResult = ttsStream;
+            } else if (msgModalities && msgModalities.includes('audio')) {
+              realtimeAudioResult = await this.agent.realtimeAudioOutputNode(
+                msg.audioStream,
+                modelSettings,
+              );
+            } else if (this.llm instanceof RealtimeModel && this.llm.capabilities.audioOutput) {
+              this.logger.error(
+                'Text message received from Realtime API with audio modality. ' +
+                  'This usually happens when text chat context is synced to the API. ' +
+                  'Try to add a TTS model as fallback or use text modality with TTS instead.',
+              );
+            } else {
+              this.logger.warn(
+                'audio output is enabled but neither tts nor realtime audio is available',
+              );
+            }
+
+            if (realtimeAudioResult) {
               const [forwardTask, _audioOut] = performAudioForwarding(
-                realtimeAudio,
+                realtimeAudioResult,
                 audioOutput,
                 abortController,
               );
               forwardTasks.push(forwardTask);
               audioOut = _audioOut;
               audioOut.firstFrameFut.await.finally(onFirstFrame);
-            } else {
-              this.logger.warn(
-                'audio output is enabled but neither tts nor realtime audio is available',
-              );
             }
           } else if (textOut) {
             textOut.firstTextFut.await.finally(onFirstFrame);
           }
-          outputs.push([msg.messageId, textOut, audioOut]);
+          outputs.push([msg.messageId, textOut, audioOut, msgModalities]);
         }
         await waitFor(forwardTasks);
       } catch (error) {
@@ -1671,7 +1743,9 @@ export class AgentActivity implements RecognitionHooks {
       }
     };
 
-    const messageOutputs: Array<[string, _TextOut | null, _AudioOut | null]> = [];
+    const messageOutputs: Array<
+      [string, _TextOut | null, _AudioOut | null, ('text' | 'audio')[] | undefined]
+    > = [];
     const tasks = [
       Task.from(
         (controller) => readMessages(controller, messageOutputs),
@@ -1750,7 +1824,7 @@ export class AgentActivity implements RecognitionHooks {
 
       if (messageOutputs.length > 0) {
         // there should be only one message
-        const [msgId, textOut, audioOut] = messageOutputs[0]!;
+        const [msgId, textOut, audioOut, msgModalities] = messageOutputs[0]!;
         let forwardedText = textOut?.text || '';
 
         if (audioOutput) {
@@ -1775,6 +1849,8 @@ export class AgentActivity implements RecognitionHooks {
           this.realtimeSession.truncate({
             messageId: msgId,
             audioEndMs: Math.floor(playbackPosition),
+            modalities: msgModalities,
+            audioTranscript: forwardedText,
           });
         }
 
@@ -1805,7 +1881,7 @@ export class AgentActivity implements RecognitionHooks {
 
     if (messageOutputs.length > 0) {
       // there should be only one message
-      const [msgId, textOut, _] = messageOutputs[0]!;
+      const [msgId, textOut, _, __] = messageOutputs[0]!;
       const message = ChatMessage.create({
         role: 'assistant',
         content: textOut?.text || '',
@@ -2020,12 +2096,14 @@ export class AgentActivity implements RecognitionHooks {
     this.wakeupMainTask();
   }
 
+  // TODO(brian): PR3 - Wrap entire drain() method with tracer.startActiveSpan('drain_agent_activity', { attributes: { 'lk.agent_label': this.agent.label } })
   async drain(): Promise<void> {
     const unlock = await this.lock.lock();
     try {
       if (this._draining) return;
 
       this.cancelPreemptiveGeneration();
+      // TODO(brian): PR3 - Wrap onExit with tracer.startActiveSpan('on_exit', { attributes: { 'lk.agent_label': this.agent.label } })
       this.createSpeechTask({
         task: Task.from(() => this.agent.onExit()),
         name: 'AgentActivity_onExit',