EstuaryClient

The main entry point for the Estuary Python SDK. Inherits from AsyncEventEmitter.

from estuary_sdk import EstuaryClient, EstuaryConfig

config = EstuaryConfig(...)
client = EstuaryClient(config)

Context Manager

EstuaryClient supports async with for automatic cleanup:

async with EstuaryClient(config) as client:
    await client.connect()
    # ... use client ...
# disconnect() is called automatically on exit

Connection Methods

connect() -> SessionInfo

Connect to the Estuary server and authenticate. Returns a SessionInfo with session details.

session = await client.connect()
print(session.session_id, session.conversation_id)

Raises: EstuaryError with AUTH_FAILED, CONNECTION_FAILED, or CONNECTION_TIMEOUT.

disconnect() -> None

Disconnect from the server and clean up all resources (voice, REST client).

await client.disconnect()

Properties

Property	Type	Description
is_connected	bool	Whether the client is currently connected
session	SessionInfo | None	Current session info, or None if not connected

Text Methods

send_text(text, text_only=False) -> None

Send a text message to the character.

Parameter	Type	Default	Description
text	str	required	The message text
text_only	bool	False	If True, suppress voice response

Raises: EstuaryError with NOT_CONNECTED.

send_text_and_wait(text, *, text_only=False, timeout=20.0) -> BotResponse

Send a text message and wait for the final bot response. Returns the complete BotResponse directly.

Parameter	Type	Default	Description
text	str	required	The message text
text_only	bool	False	If True, suppress voice response
timeout	float	20.0	Max seconds to wait for a final response

Returns: BotResponse with is_final=True.

Raises: asyncio.TimeoutError if no final response within timeout. EstuaryError with NOT_CONNECTED.

interrupt(message_id=None) -> None

Interrupt the current bot response.

Parameter	Type	Default	Description
message_id	str | None	None	Specific message to interrupt, or None for current

Voice Methods

start_voice(mode=VoiceMode.CONTINUOUS) -> None

Start a voice session.

Parameter	Type	Default	Description
mode	VoiceMode	CONTINUOUS	CONTINUOUS for VAD, PUSH_TO_TALK for manual control

Raises: EstuaryError with VOICE_ALREADY_ACTIVE, VOICE_START_FAILED, or LIVEKIT_UNAVAILABLE.

stop_voice() -> None

Stop the voice session and clean up resources.

start_recording() -> None

Begin streaming audio (push-to-talk mode only).

Raises: EstuaryError with VOICE_NOT_ACTIVE.

stop_recording() -> None

Stop streaming audio and trigger end-of-turn (push-to-talk mode only).

Raises: EstuaryError with VOICE_NOT_ACTIVE.

send_audio(audio) -> None

Send raw PCM16 audio bytes to the server.

Parameter	Type	Description
audio	bytes	Raw PCM16 audio (16-bit signed integer, mono, at configured sample rate)

Raises: EstuaryError with VOICE_NOT_ACTIVE.

toggle_mute() -> None

Toggle voice mute state.

Voice Properties

Property	Type	Description
is_voice_active	bool	Whether a voice session is currently active
is_muted	bool	Whether voice is currently muted

Vision Methods

send_camera_image(image_base64, mime_type, request_id=None, text=None) -> None

Send a camera image for vision processing.

Parameter	Type	Default	Description
image_base64	str	required	Base64-encoded image data
mime_type	str	required	Image MIME type (e.g., "image/jpeg")
request_id	str | None	None	Request ID from camera_capture_request event
text	str | None	None	Optional text to accompany the image

Agent-to-Agent Methods

start_agent_conversation(agent_a_id, agent_b_id, *, conversation_context="", max_turns=8, timeout_seconds=90) -> None

Start an agent-to-agent conversation. Events are emitted as the agents exchange turns.

Parameter	Type	Default	Description
agent_a_id	str	required	First agent ID
agent_b_id	str	required	Second agent ID
conversation_context	str	""	Context/topic for the conversation
max_turns	int	8	Maximum number of turns
timeout_seconds	int	90	Timeout in seconds

Raises: EstuaryError with NOT_CONNECTED.

stop_agent_conversation() -> None

Stop the current agent-to-agent conversation.

Raises: EstuaryError with NOT_CONNECTED.

Preferences

update_preferences(enable_vision_acknowledgment=None) -> None

Update session preferences.

notify_audio_playback_complete(message_id=None) -> None

Notify the server that audio playback has finished.

REST Sub-Clients

These are accessed as properties on the client:

client.memory -> MemoryClient

Memory REST API. Available after connect().

Method	Returns	Description
get_memories(...)	MemoryListResponse	List memories with filtering/pagination
get_timeline(...)	MemoryTimeline	Memories grouped by time period
get_stats()	MemoryStats	Aggregate memory statistics
get_core_facts()	CoreFactsResponse	High-confidence stable facts
get_graph(...)	MemoryGraph	Full knowledge graph
search(query, limit)	MemorySearchResponse	Semantic similarity search
delete_all(confirm)	MemoryDeleteResponse	Delete all memories

client.players -> PlayersClient

Players REST API. Available after connect().

Method	Returns	Description
list(...)	PlayerConversationList	List player conversations
get(player_id)	PlayerConversation	Get a single player conversation
get_messages(player_id, ...)	PlayerMessageList	Get conversation messages
get_stats()	PlayerStats	Aggregate player statistics
delete(player_id)	dict	Delete a player and all data

client.characters -> CharactersClient

Characters REST API. Available immediately (no connect() required).

Method	Returns	Description
create(name, ...)	Character	Create a new character
list(limit, offset)	CharacterListResponse	List characters
get(character_id)	Character	Get a character by ID
update(character_id, ...)	Character	Update a character
delete(character_id)	dict	Delete a character

client.generate -> GenerateClient

Character generation REST API. Available immediately (no connect() required).

Method	Returns	Description
image_to_character(image_base64, mime_type)	GeneratedCharacter	Generate a character from an image
get_model_status(agent_id)	ModelStatus	Poll 3D model generation status
wait_for_model(agent_id, *, poll_interval, timeout, on_progress)	ModelStatus	Poll until model completes or fails