Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vectorshift.ai/llms.txt

Use this file to discover all available pages before exploring further.

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
​
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
​
content
Union[str, Path, bytes, io.IOBase]
required
Message content. Accepts str, Path, bytes, or file-like objects. See Union.
​
files
Optional[Sequence[Union[Path, bytes, io.IOBase]]]
default:"None"
Optional list of additional file attachments (reserved for future use). See Union.
​
mime_type
Optional[str]
default:"None"
Optional MIME type for non-text content.
​
filename
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
​
messages
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
​
event_types
Optional[Sequence[SessionEventType]]
default:"None"
Optional filter — only events whose type is in this collection are yielded. See SessionEventType.
​
maxsize
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
​
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
​
returns
list[SessionMessage]
See SessionMessage.

​
State

​
session_id

Session.session_id -> Optional[str]  # property
Returns
​
returns
Optional[str]

​
is_connected

Session.is_connected -> bool  # property
Returns
​
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
​
type
SessionEventType
required
​
session_id
str
required
​
message_id
Optional[str]
​
data
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
​
id
str
required
​
session_id
str
required
​
sender
MessageSender
required
​
content_type
str
default:"''"
​
text
Optional[str]
​
status
Optional[SessionMessageStatus]
​
raw
dict[str, Any]
default:"{}"

​
SessionMessageStatus

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

​
MessageSender

Who sent a session message. Fields
​
role
SessionMessageRole
required
​
user_id
Optional[str]
​
object_id
Optional[str]
​
object_type
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
​
content
Union[str, Path, bytes, io.IOBase, None]
​
files
Optional[Sequence[Union[Path, bytes, io.IOBase]]]
​
mime_type
Optional[str]
​
filename
Optional[str]
​
references
Optional[Mapping[str, Any]]

​
Union