Skip to main content

Sessions & Chat

Sessions represent a conversation between a user and an agent. Each session maintains its own message history and context window. This guide covers creating sessions, sending messages (synchronously or via streaming), and retrieving conversation history.

Create a session

Start a new conversation by creating a session tied to a specific agent.
The response includes the session session_id. Store it to send messages and retrieve history.

Send a chat message (synchronous)

Send a message and wait for the complete response. This is the simplest approach and works well when you do not need to display partial results.
The response includes the assistant’s reply in assistant_response, any sources (under response.sources) referencing datasource content, and metadata such as token usage.

Stream a chat response (SSE)

For a more responsive user experience, stream the response as Server-Sent Events. Each event delivers a chunk of the assistant’s reply as it is generated.
The streaming endpoint uses Server-Sent Events (SSE). In Python each event is an SSEEvent (read event.event for the name and event.json() for the payload); in TypeScript each event is the already-parsed payload. Common event names are partial_response (the cumulative reply so far) and completion (stream finished), with connected and status events along the way.

Get session message history

Retrieve all messages exchanged in a session, in chronological order.
Each message includes type (either "user" or "assistant"), the message content, and a timestamp.

Get session details

Retrieve metadata about a session, including its agent and status.