Class AgentSession<UserData>

constructor

• new AgentSession<UserData>(options?): AgentSession<UserData>

• Type Parameters

  • UserData = unknown

  Parameters

  • options: AgentSessionOptions<UserData> = {}

  Returns AgentSession<UserData>

Optional llm

Readonly options

Readonly sessionOptions

Optional stt

Optional tts

Optional turnDetection

Optional vad

agentState

• get agentState(): AgentState

• Returns AgentState

amd

• get amd(): null | AMD

• The currently bound AMD instance, or null if AMD is not in use. Mirrors python AgentSession.amd.

  Returns null | AMD

chatCtx

• get chatCtx(): ChatContext

• Returns ChatContext

connOptions

• get connOptions(): ResolvedSessionConnectOptions

• Connection options for STT, LLM, and TTS.

  Returns ResolvedSessionConnectOptions

currentAgent

• get currentAgent(): Agent<any>

• Returns Agent<any>

history

• get history(): ChatContext

• Returns ChatContext

input

• get input(): AgentInput

• Returns AgentInput

interruptionDetection

• get interruptionDetection(): undefined | "adaptive" | "vad"

• Returns undefined | "adaptive" | "vad"

keyterms

• get keyterms(): string[]

• The effective keyterms (user-defined + auto-detected) currently applied to the STT.

  Returns string[]

output

• get output(): AgentOutput

• Returns AgentOutput

toolCtx

• get toolCtx(): ToolContext<UserData>

• Returns ToolContext<UserData>

tools

• get tools(): readonly ToolContextEntry<UserData>[]

• Returns readonly ToolContextEntry<UserData>[]

usage

• get usage(): AgentSessionUsage

• Returns usage summaries for this session, one per model/provider combination.

  Returns AgentSessionUsage

useTtsAlignedTranscript

• get useTtsAlignedTranscript(): boolean

• Returns boolean

userData

• get userData(): UserData

• Returns UserData

• set userData(value): void

• Parameters

  • value: UserData

  Returns void

userState

• get userState(): UserState

• Returns UserState

clearUserTurn

• clearUserTurn(): void

• Returns void

close

• close(): Promise<void>

• Returns Promise<void>

commitUserTurn

• commitUserTurn(): void

• Returns void

emit

• emit<K>(event, ...args): boolean

• Type Parameters

  • K extends keyof AgentSessionCallbacks

  Parameters

  • event: K
  • Rest ...args: Parameters<AgentSessionCallbacks[K]>

  Returns boolean

generateReply

• generateReply(options?): SpeechHandle

• Parameters

  • Optional options: {
        allowInterruptions?: boolean;
        chatCtx?: ChatContext;
        inputModality?: "audio" | "text";
        instructions?: string | Instructions;
        toolChoice?: llm.ToolChoice;
        userInput?: string | ChatMessage;
    }

    • Optional allowInterruptions?: boolean

    • Optional chatCtx?: ChatContext

    • Optional inputModality?: "audio" | "text"

      The input modality used for generating the reply. Defaults to "text".

    • Optional instructions?: string | Instructions

    • Optional toolChoice?: llm.ToolChoice

    • Optional userInput?: string | ChatMessage

  Returns SpeechHandle

interrupt

• interrupt(options?): Future<void, Error>

• Parameters

  • Optional options: {
        force?: boolean;
    }

    • Optional force?: boolean

  Returns Future<void, Error>

pauseReplyAuthorization

• pauseReplyAuthorization(): void

• Returns void

resumeReplyAuthorization

• resumeReplyAuthorization(): void

• Returns void

run

• run<T>(options): RunResult<T>

• Run a test with user input and return a result for assertions.

  This method is primarily used for testing agent behavior without requiring a real room connection.

  Type Parameters

  • T = unknown

  Parameters

  • options: {
        inputModality?: "audio" | "text";
        outputOptions?: null | RunOutputOptions;
        outputType?: ZodType<T, ZodTypeDef, T>;
        userInput: string;
    }

    Run options including user input and optional output type. When outputType is set and the turn ends without structured output, the run re-prompts the model up to outputOptions.maxRetries times (default 2) before rejecting with UnexpectedModelBehavior. Pass outputOptions: null to disable retries entirely.

    • Optional inputModality?: "audio" | "text"

    • Optional outputOptions?: null | RunOutputOptions

    • Optional outputType?: ZodType<T, ZodTypeDef, T>

    • userInput: string

  Returns RunResult<T>

  A RunResult that resolves when the agent finishes responding

  Example

  const result = await session.run({ userInput: 'Hello' });
  result.expect.nextEvent().isMessage({ role: 'assistant' });
  result.expect.noMoreEvents();
  Copy

say

• say(text, options?): SpeechHandle

• Parameters

  • text: string | ReadableStream<string>
  • Optional options: {
        addToChatCtx?: boolean;
        allowInterruptions?: boolean;
        audio?: ReadableStream<AudioFrame>;
    }

    • Optional addToChatCtx?: boolean

    • Optional allowInterruptions?: boolean

    • Optional audio?: ReadableStream<AudioFrame>

  Returns SpeechHandle

shutdown

• shutdown(options?): void

• Parameters

  • Optional options: {
        drain?: boolean;
        reason?: string;
    }

    • Optional drain?: boolean

    • Optional reason?: string

  Returns void

start

• start(__namedParameters): Promise<void>

• Parameters

  • __namedParameters: {
        agent: Agent<any>;
        inputOptions?: Partial<RoomInputOptions>;
        outputOptions?: Partial<RoomOutputOptions>;
        record?: boolean | RecordingOptions;
        room?: Room;
    }

    • agent: Agent<any>

    • Optional inputOptions?: Partial<RoomInputOptions>

    • Optional outputOptions?: Partial<RoomOutputOptions>

    • Optional record?: boolean | RecordingOptions

    • Optional room?: Room

  Returns Promise<void>

updateAgent

• updateAgent(agent): void

• Parameters

  • agent: Agent<any>

  Returns void

updateOptions

• updateOptions(options): void

• Parameters

  • options: AgentSessionUpdateOptions

  Returns void

waitForIdle

• waitForIdle(): Promise<AgentActivity>

• Returns Promise<AgentActivity>

waitForIdleAndHold

• waitForIdleAndHold<T>(fn): Promise<T>

• Type Parameters

  • T

  Parameters

  • fn: ((activity) => T | Promise<T>)
    • • (activity): T | Promise<T>

      • Parameters

        • activity: AgentActivity

        Returns T | Promise<T>

  Returns Promise<T>