@livekit/agents 1.0.18 → 1.0.19

package/src/telemetry/trace_types.ts

@@ -0,0 +1,88 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// LiveKit custom attributes
+export const ATTR_SPEECH_ID = 'lk.speech_id';
+export const ATTR_AGENT_LABEL = 'lk.agent_label';
+export const ATTR_START_TIME = 'lk.start_time';
+export const ATTR_END_TIME = 'lk.end_time';
+export const ATTR_RETRY_COUNT = 'lk.retry_count';
+
+export const ATTR_PARTICIPANT_ID = 'lk.participant_id';
+export const ATTR_PARTICIPANT_IDENTITY = 'lk.participant_identity';
+export const ATTR_PARTICIPANT_KIND = 'lk.participant_kind';
+
+// session start
+export const ATTR_JOB_ID = 'lk.job_id';
+export const ATTR_AGENT_NAME = 'lk.agent_name';
+export const ATTR_ROOM_NAME = 'lk.room_name';
+export const ATTR_SESSION_OPTIONS = 'lk.session_options';
+
+// assistant turn
+export const ATTR_USER_INPUT = 'lk.user_input';
+export const ATTR_INSTRUCTIONS = 'lk.instructions';
+export const ATTR_SPEECH_INTERRUPTED = 'lk.interrupted';
+
+// llm node
+export const ATTR_CHAT_CTX = 'lk.chat_ctx';
+export const ATTR_FUNCTION_TOOLS = 'lk.function_tools';
+export const ATTR_RESPONSE_TEXT = 'lk.response.text';
+export const ATTR_RESPONSE_FUNCTION_CALLS = 'lk.response.function_calls';
+
+// function tool
+export const ATTR_FUNCTION_TOOL_NAME = 'lk.function_tool.name';
+export const ATTR_FUNCTION_TOOL_ARGS = 'lk.function_tool.arguments';
+export const ATTR_FUNCTION_TOOL_IS_ERROR = 'lk.function_tool.is_error';
+export const ATTR_FUNCTION_TOOL_OUTPUT = 'lk.function_tool.output';
+
+// tts node
+export const ATTR_TTS_INPUT_TEXT = 'lk.input_text';
+export const ATTR_TTS_STREAMING = 'lk.tts.streaming';
+export const ATTR_TTS_LABEL = 'lk.tts.label';
+
+// eou detection
+export const ATTR_EOU_PROBABILITY = 'lk.eou.probability';
+export const ATTR_EOU_UNLIKELY_THRESHOLD = 'lk.eou.unlikely_threshold';
+export const ATTR_EOU_DELAY = 'lk.eou.endpointing_delay';
+export const ATTR_EOU_LANGUAGE = 'lk.eou.language';
+export const ATTR_USER_TRANSCRIPT = 'lk.user_transcript';
+export const ATTR_TRANSCRIPT_CONFIDENCE = 'lk.transcript_confidence';
+export const ATTR_TRANSCRIPTION_DELAY = 'lk.transcription_delay';
+export const ATTR_END_OF_TURN_DELAY = 'lk.end_of_turn_delay';
+
+// metrics
+export const ATTR_LLM_METRICS = 'lk.llm_metrics';
+export const ATTR_TTS_METRICS = 'lk.tts_metrics';
+export const ATTR_REALTIME_MODEL_METRICS = 'lk.realtime_model_metrics';
+
+// OpenTelemetry GenAI attributes
+// OpenTelemetry specification: https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
+export const ATTR_GEN_AI_OPERATION_NAME = 'gen_ai.operation.name';
+export const ATTR_GEN_AI_REQUEST_MODEL = 'gen_ai.request.model';
+export const ATTR_GEN_AI_USAGE_INPUT_TOKENS = 'gen_ai.usage.input_tokens';
+export const ATTR_GEN_AI_USAGE_OUTPUT_TOKENS = 'gen_ai.usage.output_tokens';
+
+// Unofficial OpenTelemetry GenAI attributes, recognized by LangFuse
+// https://langfuse.com/integrations/native/opentelemetry#usage
+// but not yet in the official OpenTelemetry specification.
+export const ATTR_GEN_AI_USAGE_INPUT_TEXT_TOKENS = 'gen_ai.usage.input_text_tokens';
+export const ATTR_GEN_AI_USAGE_INPUT_AUDIO_TOKENS = 'gen_ai.usage.input_audio_tokens';
+export const ATTR_GEN_AI_USAGE_INPUT_CACHED_TOKENS = 'gen_ai.usage.input_cached_tokens';
+export const ATTR_GEN_AI_USAGE_OUTPUT_TEXT_TOKENS = 'gen_ai.usage.output_text_tokens';
+export const ATTR_GEN_AI_USAGE_OUTPUT_AUDIO_TOKENS = 'gen_ai.usage.output_audio_tokens';
+
+// OpenTelemetry GenAI event names (for structured logging)
+export const EVENT_GEN_AI_SYSTEM_MESSAGE = 'gen_ai.system.message';
+export const EVENT_GEN_AI_USER_MESSAGE = 'gen_ai.user.message';
+export const EVENT_GEN_AI_ASSISTANT_MESSAGE = 'gen_ai.assistant.message';
+export const EVENT_GEN_AI_TOOL_MESSAGE = 'gen_ai.tool.message';
+export const EVENT_GEN_AI_CHOICE = 'gen_ai.choice';
+
+// Exception attributes
+export const ATTR_EXCEPTION_TRACE = 'exception.stacktrace';
+export const ATTR_EXCEPTION_TYPE = 'exception.type';
+export const ATTR_EXCEPTION_MESSAGE = 'exception.message';
+
+// Platform-specific attributes
+export const ATTR_LANGFUSE_COMPLETION_START_TIME = 'langfuse.observation.completion_start_time';

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/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;
@@ -289,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',
@@ -1251,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,
@@ -2092,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',

package/src/voice/agent_session.ts

@@ -14,7 +14,7 @@ import {
   type TTSModelString,
 } from '../inference/index.js';
 import { getJobContext } from '../job.js';
-import { ChatContext, ChatMessage } from '../llm/chat_context.js';
+import { AgentHandoffItem, ChatContext, ChatMessage } from '../llm/chat_context.js';
 import type { LLM, RealtimeModel, RealtimeModelError, ToolChoice } from '../llm/index.js';
 import type { LLMError } from '../llm/llm.js';
 import { log } from '../log.js';
@@ -26,6 +26,7 @@ import type { Agent } from './agent.js';
 import { AgentActivity } from './agent_activity.js';
 import type { _TurnDetector } from './audio_recognition.js';
 import {
+  type AgentEvent,
   AgentSessionEventTypes,
   type AgentState,
   type AgentStateChangedEvent,
@@ -127,6 +128,9 @@ export class AgentSession<
   private closingTask: Promise<void> | null = null;
   private userAwayTimer: NodeJS.Timeout | null = null;
 
+  /** @internal */
+  _recordedEvents: AgentEvent[] = [];
+
   constructor(opts: AgentSessionOptions<UserData>) {
     super();
 
@@ -174,6 +178,15 @@ export class AgentSession<
     this.on(AgentSessionEventTypes.UserInputTranscribed, this._onUserInputTranscribed.bind(this));
   }
 
+  emit<K extends keyof AgentSessionCallbacks>(
+    event: K,
+    ...args: Parameters<AgentSessionCallbacks[K]>
+  ): boolean {
+    const eventData = args[0] as AgentEvent;
+    this._recordedEvents.push(eventData);
+    return super.emit(event, ...args);
+  }
+
   get input(): AgentInput {
     return this._input;
   }
@@ -199,15 +212,20 @@ export class AgentSession<
   }
 
   async start({
+    // TODO(brian): PR2 - Add setupCloudTracer() call if on LiveKit Cloud with recording enabled
+    // TODO(brian): PR3 - Add span: this._sessionSpan = tracer.startSpan('agent_session'), store as instance property
+    // TODO(brian): PR4 - Add setupCloudLogger() call in setupCloudTracer() to setup OTEL logging with Pino bridge
     agent,
     room,
     inputOptions,
     outputOptions,
+    record = true,
   }: {
     agent: Agent;
     room: Room;
     inputOptions?: Partial<RoomInputOptions>;
     outputOptions?: Partial<RoomOutputOptions>;
+    record?: boolean;
   }): Promise<void> {
     if (this.started) {
       return;
@@ -247,6 +265,17 @@ export class AgentSession<
       this.logger.debug('Auto-connecting to room via job context');
       tasks.push(ctx.connect());
     }
+
+    if (record) {
+      if (ctx._primaryAgentSession === undefined) {
+        ctx._primaryAgentSession = this;
+      } else {
+        throw new Error(
+          'Only one `AgentSession` can be the primary at a time. If you want to ignore primary designation, use session.start(record=False).',
+        );
+      }
+    }
+
     // TODO(AJS-265): add shutdown callback to job context
     tasks.push(this.updateActivity(this.agent));
 
@@ -341,6 +370,8 @@ export class AgentSession<
     // TODO(AJS-129): add lock to agent activity core lifecycle
     this.nextActivity = new AgentActivity(agent, this);
 
+    const previousActivity = this.activity;
+
     if (this.activity) {
       await this.activity.drain();
       await this.activity.close();
@@ -349,6 +380,14 @@ export class AgentSession<
     this.activity = this.nextActivity;
     this.nextActivity = undefined;
 
+    this._chatCtx.insert(
+      new AgentHandoffItem({
+        oldAgentId: previousActivity?.agent.id,
+        newAgentId: agent.id,
+      }),
+    );
+    this.logger.debug({ previousActivity, agent }, 'Agent handoff inserted into chat context');
+
     await this.activity.start();
 
     if (this._input.audio) {
@@ -419,6 +458,8 @@ export class AgentSession<
       return;
     }
 
+    // TODO(brian): PR3 - Add span: if state === 'speaking' && !this._agentSpeakingSpan, create tracer.startSpan('agent_speaking') with participant attributes
+    // TODO(brian): PR3 - Add span: if state !== 'speaking' && this._agentSpeakingSpan, end and clear this._agentSpeakingSpan
     const oldState = this._agentState;
     this._agentState = state;
 
@@ -441,6 +482,8 @@ export class AgentSession<
       return;
     }
 
+    // TODO(brian): PR3 - Add span: if state === 'speaking' && !this._userSpeakingSpan, create tracer.startSpan('user_speaking') with participant attributes
+    // TODO(brian): PR3 - Add span: if state !== 'speaking' && this._userSpeakingSpan, end and clear this._userSpeakingSpan
     const oldState = this.userState;
     this.userState = state;
 

package/src/voice/audio_recognition.ts

@@ -57,6 +57,8 @@ export interface AudioRecognitionOptions {
   maxEndpointingDelay: number;
 }
 
+// TODO(brian): PR3 - Add span: private _userTurnSpan?: Span, create lazily in _ensureUserTurnSpan() method (tracer.startSpan('user_turn') with participant attributes)
+// TODO(brian): PR3 - Add span: 'eou_detection' span when running EOU detection (in runEOUDetection method)
 export class AudioRecognition {
   private hooks: RecognitionHooks;
   private stt?: STTNode;

package/src/voice/generation.ts

@@ -377,6 +377,7 @@ export function updateInstructions(options: {
   }
 }
 
+// TODO(brian): PR3 - Add @tracer.startActiveSpan('llm_node') decorator/wrapper
 export function performLLMInference(
   node: LLMNode,
   chatCtx: ChatContext,
@@ -467,6 +468,7 @@ export function performLLMInference(
   ];
 }
 
+// TODO(brian): PR3 - Add @tracer.startActiveSpan('tts_node') decorator/wrapper
 export function performTTSInference(
   node: TTSNode,
   text: ReadableStream<string>,
@@ -650,6 +652,7 @@ export function performAudioForwarding(
   ];
 }
 
+// TODO(brian): PR3 - Add @tracer.startActiveSpan('function_tool') wrapper for each tool execution
 export function performToolExecutions({
   session,
   speechHandle,