BaseAgentProvider

Abstract base class for agent providers that cover STT + LLM + TTS in a single connection.

Defined in: src/providers/base/BaseAgentProvider.ts:88

Abstract base class for agent providers that cover STT + LLM + TTS in a single connection.

See

BaseProvider for the root provider lifecycle
LiveSTTProvider for the STT interface contract
LLMProvider for the LLM interface contract
LiveTTSProvider for the TTS interface contract

Extends

BaseProviderClass

Extended by

DeepgramAgent

Constructors

Constructor

new BaseAgentProvider(config, logger?): BaseAgentProvider;

Defined in: src/providers/base/BaseAgentProvider.ts:108

Parameters

Parameter	Type
`config`	`BaseProviderConfig` & { `model?`: `string`; }
`logger?`	`Logger`

Returns

BaseAgentProvider

Overrides

BaseProviderClass.constructor

Properties

Property	Modifier	Type	Default value	Description	Overrides	Inherited from	Defined in
`audioCallback?`	`protected`	(`chunk`) => `void`	`undefined`	-	-	-	src/providers/base/BaseAgentProvider.ts:97
`config`	`readonly`	`BaseProviderConfig` & `STTProviderConfig` & `LLMProviderConfig` & `TTSProviderConfig`	`undefined`	Merged config satisfying STT + LLM + TTS duck-type checks.	`BaseProviderClass`.`config`	-	src/providers/base/BaseAgentProvider.ts:92
`initialized`	`protected`	`boolean`	`false`	Tracks whether initialize has completed successfully.	-	`BaseProviderClass`.`initialized`	src/providers/base/BaseProvider.ts:97
`logger`	`protected`	`Logger`	`undefined`	Scoped logger instance for this provider.	-	`BaseProviderClass`.`logger`	src/providers/base/BaseProvider.ts:94
`metadataCallback?`	`protected`	(`metadata`) => `void`	`undefined`	-	-	-	src/providers/base/BaseAgentProvider.ts:98
`roles`	`readonly`	readonly `ProviderRole`[]	`[]`	Pipeline roles this provider covers. Remarks Subclasses override this to declare which pipeline stages they handle. For example, BaseSTTProvider sets `['stt']`, while NativeSTT overrides to `['input', 'stt']` because it manages its own microphone. See ProviderRole for the possible role values	`BaseProviderClass`.`roles`	-	src/providers/base/BaseAgentProvider.ts:89
`transcriptionCallback?`	`protected`	(`result`) => `void`	`undefined`	-	-	-	src/providers/base/BaseAgentProvider.ts:96
`type`	`readonly`	`ProviderType`	`undefined`	Communication transport this provider uses (`'rest'` or `'websocket'`).	-	`BaseProviderClass`.`type`	src/providers/base/BaseProvider.ts:74

Accessors

isProxyMode

Get Signature

get protected isProxyMode(): boolean;

Defined in: src/providers/base/BaseProvider.ts:286

Whether the provider is in proxy mode.

Returns

boolean

true when proxyUrl is set.

Inherited from

BaseProviderClass.isProxyMode

Methods

assertAuth()

protected assertAuth(): void;

Defined in: src/providers/base/BaseProvider.ts:272

Validate that auth is configured (either apiKey or proxyUrl).

Returns

void

Remarks

Call this in onInitialize() for any provider that requires external authentication. Native providers (NativeSTT, NativeTTS) and in-browser providers (WebLLM) should NOT call this method.

Throws

ProviderInitializationError Thrown when neither apiKey nor proxyUrl is set.

Inherited from

BaseProviderClass.assertAuth

assertReady()

protected assertReady(): void;

Defined in: src/providers/base/BaseProvider.ts:255

Guard that throws if the provider has not been initialized.

Returns

void

Remarks

Call at the start of any method that requires the provider to be ready.

Throws

Error Thrown with a descriptive message when initialized is false.

Inherited from

BaseProviderClass.assertReady

cleanupPendingState()

protected cleanupPendingState(): void;

Defined in: src/providers/base/BaseAgentProvider.ts:516

Clean up all pending promises and timers. Call from your onDispose() or connection close handler.

Returns

void

connect()

abstract connect(): Promise<void>;

Defined in: src/providers/base/BaseAgentProvider.ts:135

Open the connection and complete the provider-specific handshake.

Returns

Promise<void>

A promise that resolves when the connection is ready to accept audio via sendAudio.

Remarks

Must resolve only after the connection is fully ready for audio. Subclasses should establish the WebSocket, negotiate protocol settings, and call emitOutputMetadata before resolving.

Throws

ProviderConnectionError if the handshake fails or the connection cannot be established.

disconnect()

disconnect(): Promise<void>;

Defined in: src/providers/base/BaseAgentProvider.ts:197

No-op — the agent connection is persistent.

Returns

Promise<void>

Remarks

The orchestrator calls stt.disconnect() / tts.disconnect() during turn-taking and barge-in. For agent providers, the connection must not be torn down between turns. The real close happens in dispose().

dispose()

dispose(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:154

Clean up resources and dispose of the provider.

Returns

Promise<void>

Remarks

Delegates to the subclass hook onDispose and resets the initialized flag. If the provider is not initialized, the call is a no-op.

Throws

Re-throws any error raised by onDispose.

Inherited from

BaseProviderClass.dispose

emitAssistantText()

protected emitAssistantText(text): void;

Defined in: src/providers/base/BaseAgentProvider.ts:437

Deliver the assistant’s response text. Resolves the pending generateFromMessages iterator.

Parameters

Parameter	Type	Description
`text`	`string`	The assistant’s response text received from the agent server.

Returns

void

emitAudioChunk()

protected emitAudioChunk(data): void;

Defined in: src/providers/base/BaseAgentProvider.ts:451

Forward a binary audio chunk to the output provider.

Parameters

Parameter	Type	Description
`data`	`ArrayBuffer`	Raw audio bytes to deliver via the registered audioCallback. Zero-length buffers are silently dropped.

Returns

void

emitOutputMetadata()

abstract protected emitOutputMetadata(): void;

Defined in: src/providers/base/BaseAgentProvider.ts:159

Emit audio format metadata so the output provider can decode PCM.

Returns

void

Nothing — metadata is delivered via the registered metadataCallback.

Remarks

Called after handshake and before each response turn (because BrowserAudioOutput.stop() clears metadata during barge-in). Subclasses should call this.metadataCallback?.(metadata).

emitUserTranscription()

protected emitUserTranscription(text): void;

Defined in: src/providers/base/BaseAgentProvider.ts:416

Emit a user transcription. Creates a new per-turn audio promise and triggers the orchestrator’s STT -> LLM flow.

Parameters

Parameter	Type	Description
`text`	`string`	The transcribed user speech to forward to the orchestrator’s transcription callback.

Returns

void

finalize()

finalize(): Promise<void>;

Defined in: src/providers/base/BaseAgentProvider.ts:368

Wait for the agent to finish sending all audio for the current turn.

Returns

Promise<void>

A promise that resolves when the current turn’s audio is complete or the 30 s timeout elapses.

Remarks

Resolves when the subclass calls markAudioDone, or after a 30-second safety timeout — whichever comes first. The timeout prevents the orchestrator from hanging indefinitely if the agent never signals completion.

generate()

generate(prompt, options?): Promise<AsyncIterable<string, any, any>>;

Defined in: src/providers/base/BaseAgentProvider.ts:268

Generate a response from a single user prompt.

Parameters

Parameter	Type	Description
`prompt`	`string`	The user’s text input.
`options?`	`LLMGenerationOptions`	Optional generation overrides (only `signal` is meaningful for agent providers).

Returns

Promise<AsyncIterable<string, any, any>>

An async iterable that yields the assistant’s response as a single text chunk.

Remarks

Wraps the prompt in a user message and delegates to generateFromMessages.

Throws

AbortError if the supplied options.signal is aborted before the server responds.

generateFromMessages()

generateFromMessages(_messages, _options?): Promise<AsyncIterable<string, any, any>>;

Defined in: src/providers/base/BaseAgentProvider.ts:300

Returns an async iterable that yields the assistant’s response text.

Parameters

Parameter	Type	Description
`_messages`	`LLMMessage`[]	Conversation messages (ignored — the agent server maintains its own history).
`_options?`	`LLMGenerationOptions`	Optional generation overrides. Only `signal` is observed to support abort.

Returns

Promise<AsyncIterable<string, any, any>>

An async iterable that yields the assistant’s response as a single text chunk.

Remarks

Agent APIs manage their own conversation context. This method does NOT re-send the message history — the server already has it. Instead, it returns an iterable that blocks until the server sends the assistant’s response text, then yields it as a single chunk.

The returned iterator resolves when the subclass calls emitAssistantText. If the connection closes before a response arrives, the iterator rejects via rejectPendingLLM.

Throws

AbortError if the supplied _options.signal is aborted before the server responds.

getConfig()

getConfig(): BaseProviderConfig;

Defined in: src/providers/base/BaseProvider.ts:187

Get a shallow copy of the current provider configuration.

Returns

BaseProviderConfig

A new object containing all current configuration values.

Inherited from

BaseProviderClass.getConfig

initialize()

initialize(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:127

Initialize the provider, making it ready for use.

Returns

Promise<void>

Remarks

Calls the subclass hook onInitialize. If the provider has already been initialized the call is a no-op.

Throws

ProviderInitializationError Thrown when onInitialize rejects. The original error is wrapped with the provider class name for diagnostics.

Inherited from

BaseProviderClass.initialize

isAudioReady()

isAudioReady(chunk): boolean;

Defined in: src/providers/base/BaseAgentProvider.ts:401

Check whether an audio chunk is ready for playback.

Parameters

Parameter	Type	Description
`chunk`	`AudioChunk`	The audio chunk to inspect.

Returns

boolean

true when the chunk contains a non-empty audio buffer.

isFinal()

isFinal(result): boolean;

Defined in: src/providers/base/BaseAgentProvider.ts:245

Check whether a transcription is a final result.

Parameters

Parameter	Type	Description
`result`	`TranscriptionResult`	The transcription result to inspect.

Returns

boolean

true when the result has isFinal set.

isInterim()

isInterim(_result): boolean;

Defined in: src/providers/base/BaseAgentProvider.ts:235

Check whether a transcription is an interim (non-final) result.

Parameters

Parameter	Type	Description
`_result`	`TranscriptionResult`	The transcription result to inspect.

Returns

boolean

Always false for agent providers.

Remarks

Agent providers only surface final transcriptions — always returns false.

isPreflight()

isPreflight(_result): boolean;

Defined in: src/providers/base/BaseAgentProvider.ts:222

Check whether a transcription is a speculative preflight result.

Parameters

Parameter	Type	Description
`_result`	`TranscriptionResult`	The transcription result to inspect.

Returns

boolean

Always false for agent providers.

Remarks

Agent providers do not emit preflight results — always returns false.

isReady()

isReady(): boolean;

Defined in: src/providers/base/BaseProvider.ts:178

Check whether the provider has been initialized and is ready.

Returns

boolean

true when initialize has completed successfully and dispose has not yet been called.

Inherited from

BaseProviderClass.isReady

isUtteranceComplete()

isUtteranceComplete(result): boolean;

Defined in: src/providers/base/BaseAgentProvider.ts:209

Check whether a transcription marks the end of an utterance.

Parameters

Parameter	Type	Description
`result`	`TranscriptionResult`	The transcription result to inspect.

Returns

boolean

true when the result has utteranceComplete set.

markAudioDone()

protected markAudioDone(): void;

Defined in: src/providers/base/BaseAgentProvider.ts:463

Signal that all audio for the current turn has been sent. Resolves the pending finalize() call.

Returns

void

onAudio()

onAudio(callback): void;

Defined in: src/providers/base/BaseAgentProvider.ts:381

Parameters

Parameter	Type	Description
`callback`	(`chunk`) => `void`	Invoked with an AudioChunk each time the agent sends a binary audio frame.

Returns

void

onConfigUpdate()

protected onConfigUpdate(_config): void;

Defined in: src/providers/base/BaseProvider.ts:242

Hook called after updateConfig merges new values.

Parameters

Parameter	Type	Description
`_config`	`Partial`<`BaseProviderConfig`>	The partial configuration that was merged.

Returns

void

Remarks

The default implementation is a no-op. Override in subclasses to react to runtime configuration changes (e.g. reconnect with a new API key).

Inherited from

BaseProviderClass.onConfigUpdate

onDispose()

abstract protected onDispose(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:229

Provider-specific disposal logic.

Returns

Promise<void>

Remarks

Subclasses must implement this method to release any resources acquired during onInitialize (e.g. close connections, free memory).

Inherited from

BaseProviderClass.onDispose

onInitialize()

abstract protected onInitialize(): Promise<void>;

Defined in: src/providers/base/BaseProvider.ts:217

Provider-specific initialization logic.

Returns

Promise<void>

Remarks

Subclasses must implement this method to perform any setup required before the provider can be used (e.g. validate credentials, open connections, load models).

Inherited from

BaseProviderClass.onInitialize

onMetadata()

onMetadata(callback): void;

Defined in: src/providers/base/BaseAgentProvider.ts:391

Parameters

Parameter	Type	Description
`callback`	(`metadata`) => `void`	Invoked with an AudioMetadata object describing the audio format (sample rate, encoding, etc.).

Returns

void

onTranscription()

onTranscription(callback): void;

Defined in: src/providers/base/BaseAgentProvider.ts:185

Parameters

Parameter	Type	Description
`callback`	(`result`) => `void`	Invoked with a TranscriptionResult each time the agent emits a user transcription event.

Returns

void

processAudio()

processAudio(chunk): void;

Defined in: src/providers/base/BaseAgentProvider.ts:175

Forward microphone audio to the agent connection.

Parameters

Parameter	Type	Description
`chunk`	`ArrayBuffer`	Raw PCM audio data from the microphone input.

Returns

void

Remarks

Alias for sendAudio — called by the orchestrator’s input queue.

See

sendAudio

processChunk()

processChunk(_text): void;

Defined in: src/providers/base/BaseAgentProvider.ts:354

No-op alias for sendText.

Parameters

Parameter	Type	Description
`_text`	`string`	Text chunk (ignored by agent providers).

Returns

void

rejectPendingLLM()

protected rejectPendingLLM(error): void;

Defined in: src/providers/base/BaseAgentProvider.ts:476

Reject the pending LLM generator with an error.

Parameters

Parameter	Type	Description
`error`	`Error`	The error to propagate to the pending generateFromMessages iterator.

Returns

void

resolveApiKey()

protected resolveApiKey(): Promise<string>;

Defined in: src/providers/base/BaseProvider.ts:321

Resolve the API key, calling the factory if apiKey is a function.

Returns

Promise<string>

The resolved API key string, or 'proxy' in proxy mode.

Inherited from

BaseProviderClass.resolveApiKey

resolveAuthHeader()

protected resolveAuthHeader(defaultAuthType?): Promise<string | undefined>;

Defined in: src/providers/base/BaseProvider.ts:366

Resolve Authorization header value for the configured auth type.

Parameters

Parameter	Type	Default value	Description
`defaultAuthType`	`"token"` \| `"bearer"`	`'token'`	The default auth type for this provider.

Returns

Promise<string | undefined>

The Authorization header value, or undefined in proxy mode.

Remarks

If apiKey is a factory function it is called to get a fresh token. Returns the header value for REST or server-side WebSocket connections:

'token' → 'Token <apiKey>'
'bearer' → 'Bearer <apiKey>'

Returns undefined in proxy mode.

Inherited from

BaseProviderClass.resolveAuthHeader

resolveBaseUrl()

protected resolveBaseUrl(defaultUrl?): string | undefined;

Defined in: src/providers/base/BaseProvider.ts:307

Resolve the base URL for this provider.

Parameters

Parameter	Type	Description
`defaultUrl?`	`string`	The provider’s default API URL. Pass `undefined` to let the underlying SDK use its own default.

Returns

string | undefined

The resolved URL, or undefined when all sources are unset.

Remarks

Priority: proxyUrl > endpoint > defaultUrl.

For WebSocket providers (this.type === 'websocket'), the proxy URL’s http(s) scheme is automatically converted to ws(s).

When no URL is configured and defaultUrl is undefined, the return value is undefined — this lets SDK-based providers (Anthropic, OpenAI) fall back to their own built-in defaults.

Inherited from

BaseProviderClass.resolveBaseUrl

resolveWsProtocols()

protected resolveWsProtocols(defaultAuthType?): Promise<string[] | undefined>;

Defined in: src/providers/base/BaseProvider.ts:342

Resolve WebSocket subprotocol for authentication.

Parameters

Parameter	Type	Default value	Description
`defaultAuthType`	`"token"` \| `"bearer"`	`'token'`	The default auth type for this provider.

Returns

Promise<string[] | undefined>

Subprotocol array for new WebSocket(url, protocols), or undefined.

Remarks

If apiKey is a factory function it is called to get a fresh token. Returns the subprotocol array for direct mode based on authType:

'token' → ['token', apiKey] (Deepgram default)
'bearer' → ['bearer', apiKey] (OAuth/Bearer tokens)

Returns undefined in proxy mode (no client-side auth needed).

Inherited from

BaseProviderClass.resolveWsProtocols

sendAudio()

abstract sendAudio(chunk): void;

Defined in: src/providers/base/BaseAgentProvider.ts:144

Send raw audio to the agent as a binary frame.

Parameters

Parameter	Type	Description
`chunk`	`ArrayBuffer`	Raw PCM audio data to forward to the agent connection.

Returns

void

sendText()

sendText(_chunk): void;

Defined in: src/providers/base/BaseAgentProvider.ts:347

No-op — TTS synthesis is handled server-side.

Parameters

Parameter	Type	Description
`_chunk`	`string`	Text chunk (ignored by agent providers).

Returns

void

startKeepAlive()

protected startKeepAlive(intervalMs?, sendFn): void;

Defined in: src/providers/base/BaseAgentProvider.ts:499

Start an auto keep-alive timer. Call from your handshake completion.

Parameters

Parameter	Type	Default value	Description
`intervalMs`	`number`	`8_000`	Interval in milliseconds between keep-alive pings. Defaults to `8000` (8 seconds).
`sendFn`	() => `void`	`undefined`	Callback invoked on each tick to send the provider-specific keep-alive message.

Returns

void

Example

this.startKeepAlive(8_000, () => {
  this.ws.send(JSON.stringify({ type: 'KeepAlive' }));
});

stopKeepAlive()

protected stopKeepAlive(): void;

Defined in: src/providers/base/BaseAgentProvider.ts:505

Stop the keep-alive timer.

Returns

void

updateConfig()

updateConfig(config): void;

Defined in: src/providers/base/BaseProvider.ts:201

Merge partial configuration updates into the current config.

Parameters

Parameter	Type	Description
`config`	`Partial`<`BaseProviderConfig`>	A partial configuration object whose keys will overwrite existing values.

Returns

void

Remarks

After merging, the subclass hook onConfigUpdate is called so providers can react to changed values at runtime.

Inherited from

BaseProviderClass.updateConfig