Skip to main content

​
What is a Session?

A session represents a single agent interaction from start to finish. It captures:

Timeline

When the interaction started and ended, plus duration.

User Context

Which user triggered the interaction.

Events

Every LLM call, tool usage, and decision in sequence.

Outcome

Whether the session succeeded or failed, plus metrics.

​
Creating Sessions

The simplest way to track sessions using the begin/finish pattern: 
import sentrial

sentrial.configure(api_key="sentrial_live_xxx")

# Begin tracking
interaction = sentrial.begin(
    user_id="user_123",          # Required: group by user
    event="chat_message",        # Event type (becomes agent name)
    input="User's question",     # Optional: input data
    convo_id="conv_456"          # Optional: conversation grouping
)

# Your agent logic...
response = agent.run(user_input)

# Finish with outcome
interaction.finish(
    output=response,
    success=True,
    estimated_cost=0.023
)

​
Full Control API

For more control over session data: 
from sentrial import SentrialClient

client = SentrialClient(api_key="sentrial_live_xxx")

# Create session with full control
session_id = client.create_session(
    name="Customer Support Request",      # Descriptive name
    agent_name="support-agent",           # Groups sessions
    user_id="user_123",                   # External user ID
    metadata={                            # Any custom data
        "ticket_id": "TKT-789",
        "channel": "web_chat",
        "priority": "high"
    }
)

# Track events manually...

# Complete session
client.complete_session(
    session_id=session_id,
    success=True,
    estimated_cost=0.045,
    prompt_tokens=1500,
    completion_tokens=500,
    custom_metrics={
        "satisfaction": 4.5,
        "resolution_time": 120
    }
)

​
Event Types

Sessions contain events that capture everything your agent does:

​
Tool Calls

When your agent uses a tool (search, API call, database query, etc.) 
client.track_tool_call(
    session_id=session_id,
    tool_name="search_knowledge_base",
    tool_input={"query": "password reset"},
    tool_output={"results": ["KB-001", "KB-002"]},
    reasoning="User asked about password reset",
    estimated_cost=0.001
)

​
Decisions

When your agent makes a choice between alternatives: 
client.track_decision(
    session_id=session_id,
    reasoning="User needs password help, will search KB first",
    alternatives=["escalate_to_human", "ask_clarifying_question"],
    confidence=0.92
)

​
Automatic Tracking

LangChain Integration — If you use LangChain, our callback handler automatically tracks all events. No manual tracking needed. Learn more about LangChain integration →
from sentrial.langchain import SentrialCallbackHandler

# Create handler
handler = SentrialCallbackHandler(client, session_id)

# Use with your agent - everything tracked automatically!
result = agent_executor.invoke(
    {"input": user_query},
    {"callbacks": [handler]}
)

# Get real usage stats
print(f"Cost: ${handler.total_cost:.4f}")
print(f"Tokens: {handler.total_tokens}")
print(f"LLM calls: {handler.llm_calls}")

​
Session Lifecycle

1

Created

Session starts when agent begins processing.
2

Events

Tool calls, decisions, and LLM calls are tracked.
3

Completed

Session ends with success/failure status and metrics.

​
Viewing Sessions

In the Sentrial dashboard, you can:
  • Browse all sessions with filters for time range, agent, user, and status
  • Replay sessions to see exactly what happened step-by-step
  • View event details including inputs, outputs, and reasoning
  • See detected issues and jump to AI diagnosis

​
Next Steps

Issues & Diagnosis

Learn how issues are automatically detected.

Python SDK Reference

Complete API for session tracking.