Session reference

Real-time session for conversational agents and chatbots. Created via agent.create_session() or chatbot.create_session(). Use as an async context manager or manually call connect/disconnect. Usage

async with await agent.create_session() as session:
    await session.send("Hello!")
    async for event in session.listen():
        if event.is_complete:
            print(event.text)
            break

Lifecycle

`connect`

async Session.connect() -> Session

Open WebSocket, create or connect to session, start background listener. Returns

Session

`disconnect`

async Session.disconnect() -> None

Stop listener, close WebSocket.

`terminate`

async Session.terminate() -> None

Terminate the session on the engine and close the WebSocket. Unlike disconnect() which just detaches this client, terminate() tells the engine to destroy the session entirely. The session cannot be resumed after termination.

Messaging

`send`

async Session.send(content: Union[str, Path, bytes, io.IOBase], *, files: Optional[Sequence[Union[Path, bytes, io.IOBase]]] = None, mime_type: Optional[str] = None, filename: Optional[str] = None) -> None

Post a single message to the session. Parameters

Union[str, Path, bytes, io.IOBase]

required

Message content. Accepts str, Path, bytes, or file-like objects. See Union.

Optional[Sequence[Union[Path, bytes, io.IOBase]]]

default:"None"

Optional list of additional file attachments (reserved for future use). See Union.

Optional[str]

default:"None"

Optional MIME type for non-text content.

Optional[str]

default:"None"

Optional filename override for bytes/IOBase content.

`send_many`

async Session.send_many(messages: Sequence[SendManyItem]) -> None

Post multiple messages as a batch (one LLM turn). Each item can be a plain string, Path, bytes, file-like object, or a UserSessionMessage for full multimodal control. All entries use the same encoding rules as send(). Parameters

Sequence[SendManyItem]

required

Streaming

`listen`

async Session.listen(*, event_types: Optional[Sequence[SessionEventType]] = None, maxsize: int = 1024) -> AsyncGenerator[SessionEvent, None]

Yield events from the background listener. If event_types is provided, only matching events are yielded. Runs until the session disconnects. Parameters

Optional[Sequence[SessionEventType]]

default:"None"

Optional filter — only events whose type is in this collection are yielded. See SessionEventType.

int

default:"1024"

Maximum size of the internal subscriber queue. When a slow consumer lets this fill up, the listener will drop the offending event and emit a synthetic ERROR event with data["error"] == "subscriber queue overflow" so the consumer can react. Pass 0 for an unbounded queue.

Returns

AsyncGenerator[SessionEvent, None]

See SessionEvent.

`get_messages`

async Session.get_messages() -> list[SessionMessage]

Fetch full session history as typed SessionMessage objects. Each message has id, session_id, sender, content_type, text, status, and the original raw dict. Returns

list[SessionMessage]

See SessionMessage.

Approvals

When a tool is gated with ToolApprovalConfig.REQUIRES_APPROVAL, the agent pauses its turn and emits a SessionEventType.APPROVAL_REQUEST event on listen(). Resume the turn by calling one of the methods below; both dispatch the same WS message but respond_approval keeps the call-site readable when you also want to override the proposed arguments or send a deny reason.

`respond`

async Session.respond(
    event: SessionEvent,
    *,
    approved: Optional[bool] = None,
    confirm: Optional[Mapping[str, Any]] = None,
    deny_reason: Optional[str] = None,
) -> None

Reply to a pause event (today: APPROVAL_REQUEST; future event types dispatch through the same call). Pass approved=True to let the tool run, approved=False to reject it. Parameters

SessionEvent

required

The paused event yielded by listen().

Optional[bool]

default:"None"

True to approve, False to reject.

Optional[Mapping[str, Any]]

default:"None"

Override the arguments the model proposed (e.g. {"num_results": 3} to cap a search). Approved calls only.

Optional[str]

default:"None"

Surfaced back to the model on rejection so it can adapt its next turn.

`respond_approval`

async Session.respond_approval(
    event: SessionEvent,
    *,
    approved: bool,
    confirm: Optional[Mapping[str, Any]] = None,
    deny_reason: Optional[str] = None,
) -> None

Approval-specific helper — same wire format as respond, but approved is required and event.type must be APPROVAL_REQUEST. Use this when you only ever respond to approvals and want the call site to enforce that. Parameters

SessionEvent

required

The APPROVAL_REQUEST event from listen().

bool

required

True to approve the proposed tool call, False to reject.

Optional[Mapping[str, Any]]

default:"None"

Replacement argument values for the approved call.

Optional[str]

default:"None"

Reason surfaced to the model on rejection.

See the session-approval-respond example for a full event loop.

State

`session_id`

Session.session_id -> Optional[str]  # property

Returns

Optional[str]

`is_connected`

Session.is_connected -> bool  # property

Returns

bool

Types

Configuration objects, response shapes, and enums used by the methods above.

`SessionEvent`

SessionEvent(type: ‘SessionEventType’, session_id: ‘str’, message_id: ‘Optional[str]’ = None, data: ‘dict[str, Any]’ = <factory>) Fields

SessionEventType

required

str

required

Optional[str]

dict[str, Any]

default:"{}"

`SessionEventType`

Members

MESSAGE_DELTA = "message_delta"
MESSAGE_COMPLETE = "message_complete"
MESSAGE_STREAMING = "message_streaming"
TOOL_CALL = "tool_call"
TOOL_RESULT = "tool_result"
THINKING = "thinking"
SEARCH_RESULT = "search_result"
APPROVAL_REQUEST = "approval_request"
REAUTH_REQUEST = "reauth_request"
ERROR = "error"
PARTICIPANT_STATUS = "participant_status"
SESSION_CREATED = "session_created"
SESSION_CONNECTED = "session_connected"
MESSAGE_POSTED = "message_posted"
MESSAGES_POSTED = "messages_posted"
PONG = "pong"

`SessionMessage`

A message from session history (returned by session.get_messages()). Fields

str

required

str

required

MessageSender

required

str

default:"''"

Optional[str]

Optional[SessionMessageStatus]

dict[str, Any]

default:"{}"

`SessionMessageStatus`

Members

STREAMING = "streaming"
COMPLETE = "complete"
ERROR = "error"

`MessageSender`

Who sent a session message. Fields

SessionMessageRole

required

Optional[str]

`UserSessionMessage`

Authored outbound message for use with session.send_many(). Each field mirrors the keyword arguments of session.send():

UserSessionMessage(content="hello")                  # text
UserSessionMessage(content=Path("doc.pdf"))          # file
UserSessionMessage(content="summarize", files=[Path("chart.png")])

Fields

Union[str, Path, bytes, io.IOBase, None]

Optional[Sequence[Union[Path, bytes, io.IOBase]]]

Optional[str]

Optional[Mapping[str, Any]]

Get started

Guides

Pipeline

Agent

Knowledge Base

Integrations

Table

Transformation

Session

Analytics

Workspace

Lifecycle

`connect`

`disconnect`

`terminate`

Messaging

`send`

`send_many`

Streaming

`listen`

`get_messages`

Approvals

`respond`

`respond_approval`

State

`session_id`

`is_connected`

Types

`SessionEvent`

`SessionEventType`

`SessionMessage`

`SessionMessageStatus`

`MessageSender`

`UserSessionMessage`

`Union`

​Lifecycle

​connect

​disconnect

​terminate

​Messaging

​send

​send_many

​Streaming

​listen

​get_messages

​Approvals

​respond

​respond_approval

​State

​session_id

​is_connected

​Types

​SessionEvent

​SessionEventType

​SessionMessage

​SessionMessageStatus

​MessageSender

​UserSessionMessage

​Union

Lifecycle

`connect`

`disconnect`

`terminate`

Messaging

`send`

`send_many`

Streaming

`listen`

`get_messages`

Approvals

`respond`

`respond_approval`

State

`session_id`

`is_connected`

Types

`SessionEvent`

`SessionEventType`

`SessionMessage`

`SessionMessageStatus`

`MessageSender`

`UserSessionMessage`

`Union`