Skip to main content
By the end of this guide, you’ll have:
  • Installed the Sentrial Python SDK
  • Created and tracked your first agent session
  • Automatic issue detection running on your sessions
  • Access to AI-powered diagnosis and code fixes

​
Prerequisites

  • Python 3.9+ or Node.js 18+
  • A Sentrial account (sign up free)
  • An API key from your organization settings

​
Step 1: Install the SDK

pip install sentrial

# For LangChain automatic tracking
pip install sentrial langchain-core

​
Step 2: Initialize & Track Sessions

Initialize the client with your API key, then create sessions to track your agent runs. 
import sentrial

# Configure with your API key (from Settings > API Keys)
sentrial.configure(api_key="sentrial_live_xxx")

# Simple API: begin/finish pattern
interaction = sentrial.begin(
    user_id="user_12345",           # Required: tracks by user
    event="support_request",        # Event type (becomes agent name)
    input="Help me reset my password",
    convo_id="conv_789"             # Optional: group related events
)

# Your agent logic runs here...
response = your_agent.run(user_input)

# Finish with outcome and metrics
interaction.finish(
    output=response,
    success=True,
    estimated_cost=0.023,           # Track costs
    custom_metrics={
        "satisfaction": 4.5,
        "resolution_time": 45
    }
)
The event parameter is how Sentrial groups sessions. Use consistent names like "support_agent" or "research_assistant".

​
Step 3: Track Events

Track key events in your agent: LLM calls, tool usage, and decisions. If you use LangChain, our callback handler automatically tracks everything: 
from sentrial import SentrialClient
from sentrial.langchain import SentrialCallbackHandler
from langchain.agents import AgentExecutor

# Initialize
client = SentrialClient(api_key="sentrial_live_xxx")
session_id = client.create_session(
    name="Customer Support",
    agent_name="support-agent",
    user_id="user_123"
)

# Create callback handler - tracks everything automatically
handler = SentrialCallbackHandler(client, session_id)

# Add to your agent
result = agent_executor.invoke(
    {"input": "User's question"},
    {"callbacks": [handler]}  # Just add this!
)

# After completion, get usage stats
print(f"Cost: ${handler.total_cost:.4f}")
print(f"Tokens: {handler.total_tokens}")

​
Option B: Manual Event Tracking

For custom agents, manually track events: 
# Track tool calls
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 needs password help"
)

# Track agent decisions
client.track_decision(
    session_id=session_id,
    reasoning="Will search KB before escalating",
    alternatives=["escalate_to_human", "ask_clarifying_question"],
    confidence=0.92
)

# Complete session with metrics
client.complete_session(
    session_id=session_id,
    success=True,
    estimated_cost=0.045,
    prompt_tokens=1500,
    completion_tokens=500
)

​
Step 4: View in Dashboard

Once sessions are tracked, open the Sentrial dashboard to see your data:

Sessions

See all agent interactions with full event timelines. Click any session to replay what happened.

Agents

View metrics per agent: success rate, latency, cost. Identify regressions quickly.

Signals

Automatically detected issues across all sessions. Click to see AI diagnosis.

Codebase

Connect GitHub and chat with AI to fix issues directly in your code.

​
Complete Example

Here’s a production-ready example with LangChain: 
from sentrial import SentrialClient
from sentrial.langchain import SentrialCallbackHandler
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_react_agent

# Initialize Sentrial
client = SentrialClient(api_key="sentrial_live_xxx")

# Your agent setup
llm = ChatOpenAI(model="gpt-4o", temperature=0)
tools = [search_kb, create_ticket, send_email]
agent = create_react_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)

def handle_request(user_input: str, user_id: str) -> str:
    """Handle request with full Sentrial tracking."""

    # Create session
    session_id = client.create_session(
        name=f"Support: {user_input[:40]}...",
        agent_name="customer-support",
        user_id=user_id
    )

    # Create handler for automatic tracking
    handler = SentrialCallbackHandler(
        client,
        session_id,
        verbose=True  # Prints tracking info
    )

    try:
        result = executor.invoke(
            {"input": user_input},
            {"callbacks": [handler]}
        )

        # Complete with real metrics from handler
        client.complete_session(
            session_id=session_id,
            success=True,
            estimated_cost=handler.total_cost,
            prompt_tokens=handler.total_prompt_tokens,
            completion_tokens=handler.total_completion_tokens
        )

        return result["output"]

    except Exception as e:
        client.complete_session(
            session_id=session_id,
            success=False,
            failure_reason=str(e)
        )
        raise

# Use it
response = handle_request(
    "I can't log into my account",
    user_id="user_12345"
)

​
Next Steps

Sessions & Events

Deep dive into session tracking and event types.

Code Integration

Connect GitHub and fix issues in your codebase.

Python SDK Reference

Complete API reference for all methods.

LangChain Integration

Automatic tracking for LangChain agents.