(inference): add debug metadata headers to inference requests (#1208)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Brian Yin <brian.yin@livekit.io>

Author: 3 people

.changeset/rare-impalas-yell.md

@@ -0,0 +1,5 @@
+---
+"@livekit/agents": patch
+---
+
+(inference): add debug metadata headers to inference requests

agents/src/inference/interruption/http_transport.ts

@@ -7,7 +7,7 @@ import { TransformStream } from 'stream/web';
 import { z } from 'zod';
 import { APIConnectionError, APIError, APIStatusError, isAPIError } from '../../_exceptions.js';
 import { log } from '../../log.js';
-import { createAccessToken } from '../utils.js';
+import { buildMetadataHeaders, createAccessToken } from '../utils.js';
 import { InterruptionCacheEntry } from './interruption_cache_entry.js';
 import type { OverlappingSpeechEvent } from './types.js';
 import type { BoundedCache } from './utils.js';
@@ -55,6 +55,7 @@ export async function predictHTTP(
     const response = await ofetch(url.toString(), {
       retry: 0,
       headers: {
+        ...buildMetadataHeaders(),
         'Content-Type': 'application/octet-stream',
         Authorization: `Bearer ${options.token}`,
       },

agents/src/inference/interruption/ws_transport.ts

@@ -8,7 +8,7 @@ import { z } from 'zod';
 import { APIConnectionError, APIStatusError, APITimeoutError } from '../../_exceptions.js';
 import { log } from '../../log.js';
 import TypedPromise from '../../typed_promise.js';
-import { createAccessToken } from '../utils.js';
+import { buildMetadataHeaders, createAccessToken } from '../utils.js';
 import { InterruptionCacheEntry } from './interruption_cache_entry.js';
 import type { OverlappingSpeechEvent } from './types.js';
 import type { BoundedCache } from './utils.js';
@@ -80,7 +80,7 @@ async function connectWebSocket(
   const url = `${baseUrl}/bargein`;
 
   const ws = new WebSocket(url, {
-    headers: { Authorization: `Bearer ${token}` },
+    headers: { ...buildMetadataHeaders(), Authorization: `Bearer ${token}` },
   });
 
   await new TypedPromise<void, APIStatusError | APITimeoutError | APIConnectionError>(

agents/src/inference/llm.ts

@@ -7,7 +7,12 @@ import * as llm from '../llm/index.js';
 import type { APIConnectOptions } from '../types.js';
 import { DEFAULT_API_CONNECT_OPTIONS } from '../types.js';
 import { type Expand, toError } from '../utils.js';
-import { type AnyString, createAccessToken, getDefaultInferenceUrl } from './utils.js';
+import {
+  type AnyString,
+  buildMetadataHeaders,
+  createAccessToken,
+  getDefaultInferenceUrl,
+} from './utils.js';
 
 export type OpenAIModels =
   | 'openai/gpt-5.4'
@@ -323,13 +328,14 @@ export class LLMStream extends llm.LLMStream {
         );
       }
 
+      const extraHeaders: Record<string, string> = {
+        ...buildMetadataHeaders(),
+        ...((requestOptions.extra_headers as Record<string, string> | undefined) ?? {}),
+      };
       if (this.provider) {
-        const extraHeaders = requestOptions.extra_headers
-          ? (requestOptions.extra_headers as Record<string, string>)
-          : {};
         extraHeaders['X-LiveKit-Inference-Provider'] = this.provider;
-        requestOptions.extra_headers = extraHeaders;
       }
+      requestOptions.extra_headers = extraHeaders;
 
       const stream = await this.client.chat.completions.create(
         {

agents/src/inference/utils.ts

@@ -4,6 +4,8 @@
 import { AccessToken } from 'livekit-server-sdk';
 import { WebSocket } from 'ws';
 import { APIConnectionError, APIStatusError } from '../_exceptions.js';
+import { getJobContext } from '../job.js';
+import { version } from '../version.js';
 
 export type AnyString = string & NonNullable<unknown>;
 
@@ -46,13 +48,38 @@ export async function createAccessToken(
   return await token.toJwt();
 }
 
+/**
+ * Build metadata headers for inference requests.
+ * Includes SDK version/platform, and optionally room/job IDs from the current job context.
+ */
+export function buildMetadataHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {
+    'User-Agent': `livekit-agents-js/${version} (node ${process.version})`,
+  };
+
+  try {
+    const ctx = getJobContext();
+    const roomSid = ctx.job.room?.sid;
+    if (roomSid) {
+      headers['X-LiveKit-Room-Id'] = roomSid;
+    }
+    if (ctx.job.id) {
+      headers['X-LiveKit-Job-Id'] = ctx.job.id;
+    }
+  } catch {
+    // No job context available — standalone inference usage
+  }
+
+  return headers;
+}
+
 export async function connectWs(
   url: string,
   headers: Record<string, string>,
   timeoutMs: number,
 ): Promise<WebSocket> {
   return new Promise<WebSocket>((resolve, reject) => {
-    const socket = new WebSocket(url, { headers: headers });
+    const socket = new WebSocket(url, { headers: { ...buildMetadataHeaders(), ...headers } });
 
     const timeout = setTimeout(() => {
       reject(new APIConnectionError({ message: 'Timeout connecting to LiveKit WebSocket' }));