Sessions
How conversation context is maintained across multiple messages.
How Sessions Work
Every chat request either creates a new session or continues an existing one. Sessions store the conversation history so the agent can reference previous messages and tool calls.
Automatic Creation
When you send a chat request without a session_id, a new session is created automatically. The response includes the new session ID in the first SSE event:
{"type": "session", "session_id": "550e8400-e29b-41d4-a716-446655440000", "is_new": true}Save this session_id and pass it in subsequent requests to continue the conversation.
Context Window
When continuing a session, the agent receives the most recent messages as context. By default, the system loads up to 10 recent messages and keeps roughly 5,000 recent-message tokens before trimming the oldest messages. A minimum of 5 messages is always kept.
Developers can adjust the per-agent auto compaction limits in the console. Compaction runs when either the recent message limit or recent token limit is crossed, whichever happens first. The token limit cannot exceed the selected model's context length.
Context compaction
When a session accumulates many messages, older messages are summarized into a compact context summary. The agent sees the summary plus the most recent messages, maintaining continuity without exceeding context limits.
Entity Context
At the start of each request, the agent automatically receives a snapshot of the end user's data:
- Up to 10 vehicles (year, make, model, trim, odometer)
- Next 5 upcoming schedules
- Last 3 recent schedules
- Next 5 upcoming milestones
- Last 5 recent milestones
- Last 5 recent documents
This lets the agent reference the user's vehicles and upcoming appointments without needing to look them up first.
Hidden Sessions
Set "overrides": { "hidden": true } when creating a new session to mark it as hidden. Hidden sessions do not appear in the Galadri Console session list but otherwise function identically.
Use cases for hidden sessions:
- Automated background tasks (nightly data enrichment, batch processing)
- System-initiated interactions (proactive recall checks, maintenance reminders)
- Internal testing or monitoring
Session Properties
| Field | Type | Description |
|---|---|---|
id | UUID | Unique session identifier. |
agent_id | UUID | The agent that owns this session. |
end_user_id | UUID | The end user this session belongs to. |
venue | string | "app", "email", or "text". Indicates the conversation channel. |
title | string | null | Auto-generated from the first message. |
unread | boolean | Whether the session has unread assistant activity. |
hidden | boolean | Whether the session is hidden from the console. |
total_token_count | integer | Cumulative tokens used in this session. |
created_at | ISO 8601 | When the session was created. |
updated_at | ISO 8601 | When the session was last active. |
List sessions via the Sessions endpoint.