Track Chat Sessions

info

This guide covers tracking chat sessions with the Agenta Python SDK. For JavaScript/TypeScript or other OpenTelemetry-based clients, see the session tracking with OpenTelemetry guide.

Chat applications often span multiple requests and traces. Session tracking groups related interactions together so you can analyze complete conversations and user journeys.

What are sessions?

A session represents a conversation or interaction that spans multiple traces. When you assign a session ID to your traces, all observations with the same ID are grouped together. This helps you:

• Analyze complete conversation flows
• Debug issues in multi-turn interactions
• Track costs and token usage per conversation
• Filter and search traces by session

Setting session IDs

Use ag.tracing.store_session() to set session information on your spans.

import agenta as ag

@ag.instrument()
def process_message(message: str, session_id: str):
    # Set session ID
    ag.tracing.store_session(
        session_id=session_id,
    )

    # Your processing logic
    response = generate_response(message)
    return response

You can also set user information to track who is interacting:

@ag.instrument()
def process_message(message: str, session_id: str, user_id: str):
    # Set session information
    ag.tracing.store_session(session_id=session_id)

    # Set user information
    ag.tracing.store_user(
        user_id=user_id,
    )

    response = generate_response(message)
    return response