Skip to main content
Sessions are automatically managed by Kuralit, but understanding how they work helps you build better AI Voice Agents.

​
How Sessions Work

​
Automatic Creation

Sessions are created automatically when:
  • WebSocket connects - New session per connection
  • First message arrives - If session doesn’t exist, create one

​
Session ID

Each session has a unique identifier:
  • Generated by client - Client generates session ID
  • Server confirms - Server may provide its own session ID
  • Used for all messages - All messages in a conversation use same session ID

​
Session State

​
Conversation History

Each session maintains its own conversation history: 
# Server side - automatically managed
session.conversation_history  # List of all messages
session.add_message(message)  # Add message to history
session.get_conversation_history()  # Get full history

​
User Metadata

Store user information in sessions: 
# Set user information
session.set_user(
    user_id="user123",
    properties={"name": "John", "preferences": {...}}
)

# Clear user information
session.clear_user()

​
Session Lifecycle

​
Creation

# Server side - automatic
# When WebSocket connects or first message arrives
session = Session(
    session_id=session_id,
    config=server_config
)

​
Usage

# All messages in a conversation use the same session ID
# Server automatically retrieves or creates session
session = sessions.get(session_id) or create_new_session(session_id)

​
Cleanup

Sessions are cleaned up when:
  • WebSocket disconnects - Connection closed
  • Session expires - After inactivity timeout
  • Server restarts - All sessions cleared

​
Best Practices

​
Session IDs

  • Generate on client - Client generates session ID
  • Reuse for continuity - Same session ID = same conversation
  • New session for new topic - Start new session for new conversation

​
Session State

  • Store user preferences - Use session metadata
  • Maintain context - Conversation history is automatic
  • Track activity - Last activity is tracked automatically

​
Next Steps