Add custom event remote session proto

agents/src/voice/agent_session.ts

@@ -61,6 +61,7 @@ import {
   type CloseEvent,
   CloseReason,
   type ConversationItemAddedEvent,
+  type CustomEvent,
   type ErrorEvent,
   type FunctionToolsExecutedEvent,
   type MetricsCollectedEvent,
@@ -157,6 +158,7 @@ export type AgentSessionCallbacks = {
   [AgentSessionEventTypes.Error]: (ev: ErrorEvent) => void;
   [AgentSessionEventTypes.Close]: (ev: CloseEvent) => void;
   [AgentSessionEventTypes.OverlappingSpeech]: (ev: OverlappingSpeechEvent) => void;
+  [AgentSessionEventTypes.CustomEvent]: (ev: CustomEvent) => void;
 };
 
 export type AgentSessionOptions<UserData = UnknownUserData> = {

agents/src/voice/events.ts

@@ -33,6 +33,7 @@ export enum AgentSessionEventTypes {
   SpeechCreated = 'speech_created',
   AgentFalseInterruption = 'agent_false_interruption',
   OverlappingSpeech = 'overlapping_speech',
+  CustomEvent = 'custom_event',
   Error = 'error',
   Close = 'close',
 }
@@ -340,6 +341,26 @@ export const createAgentFalseInterruptionEvent = ({
   createdAt,
 });
 
+export type CustomEvent = {
+  type: 'custom_event';
+  /** Maps to proto `CustomEvent.type`. */
+  eventType: string;
+  /** Maps to proto `CustomEvent.payload` (arbitrary JSON object). */
+  payload: Record<string, unknown>;
+  createdAt: number;
+};
+
+export const createCustomEvent = (
+  eventType: string,
+  payload: Record<string, unknown> = {},
+  createdAt: number = Date.now(),
+): CustomEvent => ({
+  type: 'custom_event',
+  eventType,
+  payload,
+  createdAt,
+});
+
 export type AgentEvent =
   | UserInputTranscribedEvent
   | UserStateChangedEvent
@@ -351,5 +372,6 @@ export type AgentEvent =
   | SpeechCreatedEvent
   | AgentFalseInterruptionEvent
   | OverlappingSpeechEvent
+  | CustomEvent
   | ErrorEvent
   | CloseEvent;

agents/src/voice/remote_session.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import { Duration, Timestamp } from '@bufbuild/protobuf';
+import { Duration, Struct, Timestamp } from '@bufbuild/protobuf';
 import { AgentSession as pb } from '@livekit/protocol';
 import type { ByteStreamReader, Room, TextStreamInfo } from '@livekit/rtc-node';
 import { ThrowsPromise } from '@livekit/throws-transformer/throws';
@@ -32,6 +32,7 @@ import {
   type AgentState,
   type AgentStateChangedEvent,
   type ConversationItemAddedEvent,
+  type CustomEvent,
   type ErrorEvent,
   type FunctionToolsExecutedEvent,
   type MetricsCollectedEvent,
@@ -62,6 +63,7 @@ export type RemoteSessionEventTypes =
   | 'function_tools_executed'
   | 'overlapping_speech'
   | 'amd_prediction'
+  | 'custom_event'
   | 'session_usage'
   | 'error';
 
@@ -74,10 +76,22 @@ export type RemoteSessionCallbacks = {
   function_tools_executed: (ev: pb.AgentSessionEvent_FunctionToolsExecuted) => void;
   overlapping_speech: (ev: pb.AgentSessionEvent_OverlappingSpeech) => void;
   amd_prediction: (ev: pb.AgentSessionEvent_AmdPrediction) => void;
+  custom_event: (ev: { eventType: string; payload: Record<string, unknown> }) => void;
   session_usage: (ev: pb.AgentSessionEvent_SessionUsageUpdated) => void;
   error: (ev: pb.AgentSessionEvent_Error) => void;
 };
 
+function dictToStruct(data: Record<string, unknown>): Struct {
+  return Struct.fromJson(data);
+}
+
+function structToDict(st: Struct | undefined): Record<string, unknown> {
+  if (!st) {
+    return {};
+  }
+  return st.toJson() as Record<string, unknown>;
+}
+
 // ===========================================================================
 // SessionTransport
 // ===========================================================================
@@ -522,6 +536,7 @@ export class SessionHost {
       session.on(AgentSessionEventTypes.MetricsCollected, this.onMetricsCollected);
       session.on(AgentSessionEventTypes.OverlappingSpeech, this.onOverlappingSpeech);
       session.on(AgentSessionEventTypes.Error, this.onHostError);
+      session.on(AgentSessionEventTypes.CustomEvent, this.onCustomEvent);
     }
   }
 
@@ -550,6 +565,7 @@ export class SessionHost {
       this.session.off(AgentSessionEventTypes.MetricsCollected, this.onMetricsCollected);
       this.session.off(AgentSessionEventTypes.OverlappingSpeech, this.onOverlappingSpeech);
       this.session.off(AgentSessionEventTypes.Error, this.onHostError);
+      this.session.off(AgentSessionEventTypes.CustomEvent, this.onCustomEvent);
     }
 
     if (this.recvTask) {
@@ -713,6 +729,19 @@ export class SessionHost {
     );
   };
 
+  private onCustomEvent = (event: CustomEvent): void => {
+    this.emitEvent(
+      {
+        case: 'customEvent',
+        value: new pb.CustomEvent({
+          type: event.eventType,
+          payload: dictToStruct(event.payload),
+        }),
+      },
+      event.createdAt,
+    );
+  };
+
   /**
    * @internal — forwards an AMD prediction to the connected
    * {@link RemoteSession} peer. Mirrors python
@@ -1007,6 +1036,12 @@ export class RemoteSession extends (EventEmitter as new () => TypedEventEmitter<
       case 'error':
         this.emit('error', ev.value);
         break;
+      case 'customEvent':
+        this.emit('custom_event', {
+          eventType: ev.value.type,
+          payload: structToDict(ev.value.payload),
+        });
+        break;
     }
   }
 

examples/src/multi_agent.ts

@@ -102,4 +102,10 @@ export default defineAgent({
   },
 });
 
-cli.runApp(new ServerOptions({ agent: fileURLToPath(import.meta.url) }));
+cli.runApp(
+  new ServerOptions({
+    agent: fileURLToPath(import.meta.url),
+    // Enables explicit dispatch so agents-cli can summon this worker by name.
+    agentName: 'multi-agent-js',
+  }),
+);