Sessions & Events

Understanding the core concepts of how Sentrial tracks agent executions.

What is a Session?

A session represents a single execution of your AI agent from start to finish. Think of it like a single conversation or task that your agent handles.

Session Lifecycle

1
Create - Initialize a new session with a name and metadata
2
Track - Log events as your agent executes (tool calls, decisions, LLM calls)
3
Close - Mark the session as complete with a final status

from sentrial import SentrialClient

client = SentrialClient(api_key="...", project_id="...")

# 1. Create session
session_id = client.create_session(
    name="Customer Support - Password Reset",
    metadata={
        "user_id": "user_123",
        "ticket_id": "TICKET-456"
    }
)

# 2. Track events (agent executes)
client.track_tool_call(...)
client.track_decision(...)

# 3. Close session
client.close_session(session_id, status="success")

What are Events?

Events are individual actions or decisions that happen during a session. Each event represents a single step in your agent's execution.

Tool Call Events

Track when your agent uses a tool or calls a function.

Example: Agent calls search_knowledge_base(query="password reset")

Decision Events

Track agent reasoning, thought process, and decision-making.

Example: Agent decides to escalate to human support after KB search fails

LLM Call Events

Track calls to language models with prompts, responses, and token usage.

Example: Agent generates email response using GPT-4

Error Events

Track errors and exceptions that occur during execution.

Example: Knowledge base API timeout

Session Metadata

Add custom metadata to sessions for filtering and organization:

session_id = client.create_session(
    name="Support Agent",
    metadata={
        # User context
        "user_id": "user_123",
        "user_email": "user@example.com",
        
        # Business context
        "ticket_id": "TICKET-456",
        "priority": "high",
        "category": "password_reset",
        
        # Environment
        "environment": "production",
        "version": "2.1.0",
        
        # Custom tags
        "tags": ["password", "authentication"]
    }
)

Use metadata to filter sessions in the dashboard, analyze patterns, and debug issues.

Event Ordering & Timing

Events are automatically timestamped and ordered chronologically. This allows you to:

Replay execution history step-by-step
Measure time between events
Identify performance bottlenecks
Debug race conditions and timing issues

Timeline View

00:00.000

Session created

00:00.120

Tool call: search_kb

00:00.385

Decision: Escalate to human

00:01.200

Session completed

Best Practices

✓ DO

Use descriptive session names (e.g., "Support - Password Reset" not "Session 1")
Add relevant metadata for filtering and debugging
Close sessions when complete
Track all major decisions and tool calls

✗ DON'T

Reuse session IDs across multiple agent runs
Store sensitive data in metadata (use encrypted references instead)
Create sessions for every single function call (group related work)
Forget to close sessions (they'll auto-close after 24h but it's better to be explicit)