Events & Types

Events

The EstuaryClient emits the following events. Register handlers with client.on("event_name", handler).

All event handlers must be async functions.

Connection Events

Event	Callback Signature	Description
connected	async (session: SessionInfo)	Connection established and authenticated
disconnected	async (reason: str)	Disconnected from server
reconnecting	async (attempt: int)	Attempting to reconnect
connection_state_changed	async (state: ConnectionState)	Connection state transition
error	async (error: Exception)	General error
auth_error	async (message: str)	Authentication failed
quota_exceeded	async (data: QuotaExceededData)	Usage quota exceeded

Response Events

Event	Callback Signature	Description
bot_response	async (response: BotResponse)	Text response chunk from the character
bot_voice	async (voice: BotVoice)	Voice audio chunk from the character
stt_response	async (response: SttResponse)	Speech-to-text transcription result
interrupt	async (data: InterruptData)	Response was interrupted

Voice Events

Event	Callback Signature	Description
voice_started	async ()	Voice session started
voice_stopped	async ()	Voice session stopped
voice_error	async (message: str)	Voice-specific error
audio_received	async (audio: bytes)	Decoded audio from LiveKit
livekit_connected	async (room: str)	LiveKit room connected
livekit_disconnected	async ()	LiveKit room disconnected

Vision Events

Event	Callback Signature	Description
camera_capture_request	async (request: CameraCaptureRequest)	Server requests a camera image

Memory Events

Event	Callback Signature	Description
memory_updated	async (event: MemoryUpdatedEvent)	New memories extracted (requires realtime_memory=True)

Agent-to-Agent Events

Event	Callback Signature	Description
agent_turn_text	async (event: AgentTurnText)	Streaming text chunk from an agent turn
agent_turn_voice	async (event: AgentTurnVoice)	Streaming voice audio chunk from an agent turn
agent_turn_complete	async (event: AgentTurnComplete)	An agent finished its turn
agent_conversation_complete	async (event: AgentConversationComplete)	Agent-to-agent conversation finished

Enums

ConnectionState

from estuary_sdk import ConnectionState

ConnectionState.DISCONNECTED   # "disconnected"
ConnectionState.CONNECTING     # "connecting"
ConnectionState.CONNECTED      # "connected"
ConnectionState.RECONNECTING   # "reconnecting"
ConnectionState.ERROR          # "error"

VoiceMode

from estuary_sdk import VoiceMode

VoiceMode.CONTINUOUS     # VAD-based turn detection
VoiceMode.PUSH_TO_TALK   # Manual start/stop recording

ErrorCode

from estuary_sdk import ErrorCode

ErrorCode.CONNECTION_FAILED     # WebSocket connection failed
ErrorCode.AUTH_FAILED           # Invalid API key
ErrorCode.CONNECTION_TIMEOUT    # Connection timed out
ErrorCode.QUOTA_EXCEEDED        # Usage limit reached
ErrorCode.VOICE_NOT_SUPPORTED   # Voice not available
ErrorCode.VOICE_ALREADY_ACTIVE  # start_voice() called twice
ErrorCode.VOICE_NOT_ACTIVE      # Voice method called without start_voice()
ErrorCode.VOICE_START_FAILED    # Voice session failed to start
ErrorCode.LIVEKIT_UNAVAILABLE   # livekit package not installed
ErrorCode.NOT_CONNECTED         # Method called before connect()
ErrorCode.REST_ERROR            # REST API request failed
ErrorCode.UNKNOWN               # Unclassified error

EstuaryError

from estuary_sdk import EstuaryError, ErrorCode

try:
    await client.connect()
except EstuaryError as err:
    print(err.code)     # ErrorCode enum value
    print(err.message)  # Human-readable message
    print(err.details)  # Optional additional context