session-storage.md
1 --- 2 title: Session Storage 3 sidebar_position: 350 4 --- 5 6 # Configuring Session Storage 7 8 This guide explains how to configure session storage in Agent Mesh, enabling user conversations to persist across restarts and providing rich conversation history for both the WebUI Gateway and individual agents. 9 10 ## Understanding Session Storage Architecture 11 12 Agent Mesh uses a distributed session architecture where the WebUI Gateway and agents maintain separate but coordinated session storage systems connected via session IDs. 13 14 ### How Session Storage Works 15 16 When a user starts a conversation: 17 18 1. The WebUI Gateway generates a session ID (`web-session-<UUID>`) 19 2. The WebUI Gateway sends the session ID to the agent with each message 20 3. The agent receives the session ID and uses it to look up or store its own session context 21 4. The WebUI Gateway and agent store different data in their own databases 22 23 This architecture allows: 24 - The WebUI Gateway to show conversation history in the user interface 25 - Agents to maintain their own conversation context and memory 26 - Multiple agents in a conversation to share the same session ID while maintaining isolated storage 27 28 ### Where Data Is Stored 29 30 The WebUI Gateway database stores: 31 - Session metadata (session ID, user ID, timestamps) 32 - Chat history displayed in the UI 33 - Message bubbles and formatted responses 34 - Task metadata (agent names, status, feedback) 35 36 Each agent database stores: 37 - Agent's conversation context and memory 38 - Message history from the agent's perspective 39 - Agent internal state and tool execution history 40 - Session events and actions 41 42 These are separate databases. Each agent has its own independent database (with separate credentials), and the WebUI Gateway has its own database. They coordinate via the session ID. 43 44 ## Session Storage Scenarios 45 46 The behavior of your deployment depends on whether the WebUI Gateway and agents have persistent storage enabled. Understanding these scenarios helps you configure correctly for your needs. 47 48 ### Scenario A: Both WebUI Gateway and Agents Have Persistence (Recommended) 49 50 ```yaml 51 # WebUI Gateway Configuration 52 session_service: 53 type: "sql" 54 database_url: "${WEB_UI_GATEWAY_DATABASE_URL}" 55 ``` 56 57 ```yaml 58 # Agent Configuration 59 session_service: 60 type: "sql" 61 database_url: "${AGENT_DATABASE_URL, sqlite:///agent-session.db}" 62 default_behavior: "PERSISTENT" 63 ``` 64 65 What happens: 66 - User sees full chat history in the UI after restarts 67 - Agents remember full conversation context across restarts 68 - Multi-turn conversations work perfectly 69 - Browser refresh preserves everything 70 71 Use this for: 72 - Production deployments 73 - Multi-turn interactive experiences 74 - Any deployment where users expect conversation continuity 75 76 ### Scenario B: Neither Has Persistence (Ephemeral Only) 77 78 ```yaml 79 # WebUI Gateway Configuration 80 session_service: 81 type: "memory" 82 ``` 83 84 ```yaml 85 # Agent Configuration 86 session_service: 87 type: "memory" 88 ``` 89 90 What happens: 91 - Sessions exist only in browser cookies 92 - No conversation history after browser refresh 93 - No persistence across restarts 94 - Everything lost when cookies expire 95 96 Use this for: 97 - Local development and testing only 98 - Rapid prototyping 99 - Scenarios where no persistence is needed 100 101 Do not use for: 102 - Production deployments 103 - Multi-turn conversations 104 - Any scenario requiring conversation continuity 105 106 ### Scenario C: Only Agents Have Persistence (Limited Experience) 107 108 ```yaml 109 # WebUI Gateway Configuration 110 session_service: 111 type: "memory" # No database 112 ``` 113 114 ```yaml 115 # Agent Configuration 116 session_service: 117 type: "sql" 118 database_url: "${AGENT_DATABASE_URL}" 119 default_behavior: "PERSISTENT" 120 ``` 121 122 What happens: 123 - User sees no chat history in the UI after browser refresh 124 - Agents maintain conversation context internally 125 - Conversation works but UI does not show history 126 127 Use this for: 128 - Rare scenarios where UI history is not needed 129 - Headless or API-only deployments without WebUI 130 131 ### Scenario D: Only WebUI Gateway Has Persistence (Broken Experience) 132 133 ```yaml 134 # WebUI Gateway Configuration 135 session_service: 136 type: "sql" 137 database_url: "${WEB_UI_GATEWAY_DATABASE_URL}" 138 ``` 139 140 ```yaml 141 # Agent Configuration 142 session_service: 143 type: "memory" # No database 144 ``` 145 146 :::warning Broken Experience 147 What happens: 148 - User sees full chat history in the UI 149 - Agent receives session ID but has no database to store context 150 - Agent processes current message but forgets previous turns 151 - The UI shows history, but the agent acts like every message is the first one 152 153 The UI misleads the user by showing conversation history that the agent cannot actually use. Users get frustrated when the agent does not remember what they just said. 154 155 Avoid this scenario because it creates a confusing and broken user experience. 156 ::: 157 158 ## Configuring WebUI Gateway Session Storage 159 160 The WebUI Gateway requires two configuration elements to enable persistent session storage. 161 162 ### Environment Variables 163 164 `SESSION_SECRET_KEY` (Required) 165 166 A secret key used to sign session cookies. This must be the same across all instances if you run multiple pods or processes. 167 168 ```bash 169 export SESSION_SECRET_KEY="your-secret-key-here" 170 ``` 171 172 `WEB_UI_GATEWAY_DATABASE_URL` (Required for persistent mode) 173 174 The database connection string specifying where to store session data. 175 176 ```bash 177 export WEB_UI_GATEWAY_DATABASE_URL="postgresql://user:pass@host:5432/webui_db" 178 ``` 179 180 `PLATFORM_DATABASE_URL` (Optional, required for enterprise features) 181 182 The database connection string for platform features such as agents, connectors, and deployments. If not configured, platform endpoints return 501 (Not Implemented). 183 184 ```bash 185 export PLATFORM_DATABASE_URL="postgresql://user:pass@host:5432/platform_db" 186 ``` 187 188 For development, you can use SQLite: 189 190 ```bash 191 export PLATFORM_DATABASE_URL="sqlite:///platform.db" 192 ``` 193 194 ### Gateway Configuration File 195 196 Update your WebUI Gateway configuration to use the database: 197 198 ```yaml 199 session_service: 200 type: "sql" 201 database_url: "${WEB_UI_GATEWAY_DATABASE_URL}" 202 203 platform_service: 204 database_url: "${PLATFORM_DATABASE_URL, sqlite:///platform.db}" 205 ``` 206 207 ### Database Backend Options 208 209 #### SQLite (Development) 210 211 SQLite stores session data in a local file, ideal for development without external infrastructure. Requires SQLite 3.35.0 or later. 212 213 ```yaml 214 session_service: 215 type: "sql" 216 database_url: "sqlite:///webui-gateway.db" 217 ``` 218 219 ```bash 220 export WEB_UI_GATEWAY_DATABASE_URL="sqlite:///webui-gateway.db" 221 ``` 222 223 Advantages: 224 - No external dependencies 225 - Instant setup 226 - Perfect for local development 227 228 Limitations: 229 - Not suitable for production 230 - Cannot be shared across multiple instances 231 - No built-in replication or backup 232 233 #### PostgreSQL (Production) 234 235 PostgreSQL provides robust, scalable database suitable for production deployments. 236 237 ```yaml 238 session_service: 239 type: "sql" 240 database_url: "postgresql://user:password@host:5432/webui_db" 241 ``` 242 243 ```bash 244 export WEB_UI_GATEWAY_DATABASE_URL="postgresql://webui_user:secure_pass@db.example.com:5432/webui_db" 245 ``` 246 247 Advantages: 248 - Production-grade reliability 249 - Horizontal scalability (multiple instances share same database) 250 - Cloud-managed options (AWS RDS, Google Cloud SQL, Azure Database) 251 - Connection pooling support 252 - ACID compliance 253 254 Connection string format: 255 ``` 256 postgresql://[user[:password]@][host][:port]/[dbname][?param1=value1&...] 257 ``` 258 259 #### MySQL/MariaDB (Production) 260 261 MySQL and MariaDB are popular open-source databases suitable for production. 262 263 ```yaml 264 session_service: 265 type: "sql" 266 database_url: "mysql+pymysql://user:password@host:3306/webui_db" 267 ``` 268 269 ```bash 270 export WEB_UI_GATEWAY_DATABASE_URL="mysql+pymysql://webui_user:secure_pass@db.example.com:3306/webui_db" 271 ``` 272 273 Advantages: 274 - Open-source and widely available 275 - Strong community support 276 - Cloud-managed options available 277 - ACID compliance (with InnoDB) 278 279 Connection string format: 280 ``` 281 mysql+pymysql://[user[:password]@][host][:port]/[database] 282 ``` 283 284 Agent Mesh uses `pymysql` as the Python driver. 285 286 ## Configuring Agent Session Storage 287 288 Agents use the ADK (Agent Development Kit) session configuration system. Each agent can be configured independently with its own database. 289 290 ### Agent Configuration File 291 292 Add the `session_service` section to your agent's YAML configuration: 293 294 ```yaml 295 session_service: 296 type: "sql" 297 database_url: "${AGENT_DATABASE_URL, sqlite:///agent-session.db}" 298 default_behavior: "PERSISTENT" 299 ``` 300 301 Parameters: 302 - `type`: `"memory"` (ephemeral) or `"sql"` (persistent) 303 - `database_url`: Connection string for the agent's database 304 - `default_behavior`: `"PERSISTENT"` (reuse sessions) or `"RUN_BASED"` (new session per run) 305 306 ### Auto-Compaction for Long Conversations 307 308 Agents automatically compact conversation history when context limits are exceeded. This feature is enabled by default and requires no configuration. 309 310 When an LLM returns a context window overflow error, the system intercepts it and automatically compacts the first N% of conversation turns (where N is the compaction_percentage), then retries the request. You can control what percentage of history is compacted using the `compaction_percentage` setting: 311 312 ```yaml 313 auto_summarization: 314 # Compact 50% of conversation history when limits are reached 315 # Default: 0.25 (25%) 316 # Range: 0.0 - 1.0 (e.g., 0.25 = 25%, 0.5 = 50%, 0.8 = 80%) 317 compaction_percentage: 0.5 318 ``` 319 320 The system always compacts up to the nearest complete conversation turn and preserves at least one recent turn uncompacted. 321 322 ### Manual Compaction 323 324 Users can also compact (compress) a conversation manually from the chat UI before the context window overflows. A per-session context-usage indicator below the chat input shows how much of the model's context window has been consumed (see [Context Usage Indicator](./model_configurations.md#context-usage-indicator) for how the limit is resolved). 325 326 Once the conversation has enough history to compact — at least a few messages or 50%+ context usage — an expandable panel surfaces a **Compress Conversation** button, and a collapsed toolbar icon appears once usage exceeds 80%. Compaction uses the same `compaction_percentage` setting as the auto path, so the behavior is identical; it just runs on user request instead of on an overflow error. Older messages are summarized, the chat history stays visible to the user, and subsequent turns use the summary instead of the original messages. 327 328 ### Environment Variables 329 330 Each agent can have its own database credentials: 331 332 ```bash 333 export AGENT_DATABASE_URL="postgresql://agent_user:agent_pass@host:5432/agent_db" 334 ``` 335 336 Or use a default with fallback in the YAML: 337 338 ```yaml 339 database_url: "${AGENT_DATABASE_URL, sqlite:///agent-session.db}" 340 ``` 341 342 ### Database Isolation Between Agents 343 344 Each agent should have: 345 - Its own separate database (not just a schema) 346 - Its own separate credentials (username and password) 347 - Complete isolation from other agents' data 348 349 Example for two agents: 350 351 ```yaml 352 # Agent A Configuration 353 session_service: 354 type: "sql" 355 database_url: "${AGENT_A_DATABASE_URL, sqlite:///agent-a.db}" 356 default_behavior: "PERSISTENT" 357 ``` 358 359 ```yaml 360 # Agent B Configuration 361 session_service: 362 type: "sql" 363 database_url: "${AGENT_B_DATABASE_URL, sqlite:///agent-b.db}" 364 default_behavior: "PERSISTENT" 365 ``` 366 367 ```bash 368 # Environment variables for isolation 369 export AGENT_A_DATABASE_URL="postgresql://agent_a_user:pass@host:5432/agent_a_db" 370 export AGENT_B_DATABASE_URL="postgresql://agent_b_user:pass@host:5432/agent_b_db" 371 ``` 372 373 ### Shared Configuration Pattern 374 375 If all agents should use the same session storage configuration, use YAML anchors: 376 377 ```yaml 378 # Shared configuration 379 session_service: &default_session_service 380 type: "sql" 381 database_url: "${SESSION_DATABASE_URL, sqlite:///session.db}" 382 default_behavior: "PERSISTENT" 383 384 # Agent references shared config 385 agents: 386 - name: agent-a 387 session_service: *default_session_service 388 389 - name: agent-b 390 session_service: *default_session_service 391 ``` 392 393 ## Migrating from Ephemeral to Persistent 394 395 Moving from ephemeral mode to persistent mode can be done without losing active sessions. 396 397 ### Step 1: Configure WebUI Gateway Database 398 399 Set the environment variables: 400 401 ```bash 402 export SESSION_SECRET_KEY="your-secret-key" 403 export WEB_UI_GATEWAY_DATABASE_URL="postgresql://user:pass@host:5432/webui_db" 404 ``` 405 406 Update your WebUI Gateway configuration: 407 408 ```yaml 409 session_service: 410 type: "sql" 411 database_url: "${WEB_UI_GATEWAY_DATABASE_URL}" 412 ``` 413 414 ### Step 2: Configure Agent Databases 415 416 For each agent, set the database URL: 417 418 ```bash 419 export AGENT_DATABASE_URL="postgresql://agent_user:pass@host:5432/agent_db" 420 ``` 421 422 Update agent configuration: 423 424 ```yaml 425 session_service: 426 type: "sql" 427 database_url: "${AGENT_DATABASE_URL}" 428 default_behavior: "PERSISTENT" 429 ``` 430 431 ### Step 3: Restart Application 432 433 When the application restarts: 434 - Database migrations run automatically 435 - Tables are created for session storage 436 - No manual database setup required 437 438 Tables created: 439 - `sessions` - Session metadata 440 - `chat_tasks` - Conversation messages 441 - Supporting indexes for performance 442 443 ### Step 4: Verify Migration 444 445 Test that persistence is working: 446 447 1. Start a conversation with an agent 448 2. Send a message 449 3. Restart the application 450 4. Refresh your browser 451 5. Verify conversation history is visible 452 6. Send another message to the same agent 453 7. Verify agent remembers previous conversation context 454 455 ### Migration Considerations 456 457 Existing cookies remain valid. Sessions stored only in cookies before migration continue to work until cookies expire. 458 459 Database initialization happens once on first startup. Subsequent restarts connect to the existing database. 460 461 Migration adds new storage without affecting existing sessions. 462 463 ## Next Steps 464 465 After configuring session storage, you may want to: 466 467 - Configure [Artifact Storage](./artifact-storage.md) for agent-generated files 468 - Review [deployment options](../deploying/deployment-options.md) for production considerations 469 - Set up [monitoring and observability](../deploying/observability.md) to track session activity