Sessions

Sessions group related traces from a single user interaction or conversation.

What is a Session?

A session represents a continuous user interaction that may span multiple requests:

Session (session_id: sess-abc123)
├── Trace 1: "Hello, how can I help?"
├── Trace 2: "Search for Python tutorials"
├── Trace 3: "Show me the first result"
└── Trace 4: "Thanks, goodbye"

Creating Sessions

Automatic

Sessions are created automatically when you provide a session ID:

from risicare import session_context
 
async def handle_message(user_id: str, session_id: str, message: str):
    with session_context(session_id=session_id, user_id=user_id):
        response = await agent.process(message)
        return response

With Metadata

Add context to sessions:

with session_context(
    session_id="sess-abc123",
    user_id="user-456",
    metadata={
        "source": "web",
        "device": "mobile",
        "locale": "en-US"
    }
):
    # All traces here belong to this session
    await process_request()

Session Attributes

Session List View

View all sessions with:

Session Detail View

Timeline

Visual timeline showing:

• All traces in chronological order
• Gaps between interactions
• Error highlights
• Token/cost per trace

Conversation View

For chat-based agents:

• Message bubbles
• User and assistant messages
• Tool call results
• Thinking indicators

Metrics

Session-level metrics:

• Total latency
• Average response time
• Token usage breakdown
• Cost breakdown
• Error rate

Filtering Sessions

# By user
user:user-123

# By time
last 24 hours
date:2024-01-15

# By activity
trace_count:>5
duration:>300000

# By cost
cost:>1.00

# By status
has_errors:true

Session Analytics

User Journey

Track common paths through your agent:

1. Most frequent first actions
2. Common conversation flows
3. Drop-off points
4. Resolution patterns

Engagement Metrics

Session Continuity

Sessions are automatically extended when activity resumes:

# First interaction
with session_context(session_id="sess-123"):
    await process("Hello")
 
# 5 minutes later - same session
with session_context(session_id="sess-123"):
    await process("I have a follow-up question")

Session timeout: 30 minutes of inactivity.

Privacy Considerations

User ID Hashing

For privacy, hash user IDs before sending:

import hashlib
 
def hash_user_id(user_id: str) -> str:
    return hashlib.sha256(user_id.encode()).hexdigest()[:16]
 
with session_context(
    session_id=session_id,
    user_id=hash_user_id(real_user_id)
):
    # ...

Next Steps