Python SDK

Complete API reference for the Sentrial Python SDK.

Installation

pip install sentrial

# With LangChain support
pip install sentrial[langchain]

SentrialClient

The main client class for interacting with the Sentrial API.

Constructor

from sentrial import SentrialClient

client = SentrialClient(
    api_key="your-api-key",           # Optional if SENTRIAL_API_KEY env var set
    project_id="your-project-id",     # Optional if SENTRIAL_PROJECT_ID env var set
    api_url="https://api.realm.ai",   # Optional, defaults to production
    timeout=30,                        # Optional, request timeout in seconds
    max_retries=3                      # Optional, max number of retries
)

Parameters:

api_key (str, optional) - Your Sentrial API key
project_id (str, optional) - Your project ID
api_url (str, optional) - API base URL
timeout (int, optional) - Request timeout in seconds
max_retries (int, optional) - Maximum retry attempts

Session Management

create_session

Create a new tracking session for your agent.

session_id = client.create_session(
    name="Customer Support Agent",
    metadata={
        "user_id": "user_123",
        "environment": "production"
    }
)

# Returns: str (session_id)

get_session

Retrieve session details.

session = client.get_session(session_id)

# Returns: dict with session details
# {
#     "id": "session_123",
#     "name": "Customer Support Agent",
#     "status": "active",
#     "created_at": "2025-01-01T00:00:00Z",
#     "metadata": {...}
# }

close_session

Mark a session as completed.

client.close_session(
    session_id,
    status="success",  # or "error", "cancelled"
    summary="Successfully helped user reset password"
)

# Returns: None

Event Tracking

track_tool_call

Track a tool/function call made by your agent.

client.track_tool_call(
    session_id=session_id,
    tool_name="search_knowledge_base",
    tool_input={
        "query": "password reset",
        "max_results": 5
    },
    tool_output={
        "articles": ["KB-001", "KB-002"],
        "relevance_scores": [0.95, 0.87]
    },
    reasoning="User mentioned password issues",
    duration_ms=150,  # Optional
    status="success"  # Optional: "success" or "error"
)

# Returns: str (event_id)

track_decision

Track agent reasoning and decision-making.

client.track_decision(
    session_id=session_id,
    reasoning="User has tried KB articles. Escalating to human support.",
    alternatives=[
        "Try another knowledge base article",
        "Ask user for more details",
        "Escalate to human support"
    ],
    chosen="Escalate to human support",
    confidence=0.85,
    metadata={
        "kb_articles_tried": 3,
        "user_frustration_level": "high"
    }
)

# Returns: str (event_id)

track_llm_call

Track LLM API calls with token usage and cost.

client.track_llm_call(
    session_id=session_id,
    model="gpt-4",
    prompt="Generate a professional password reset email...",
    response="Dear user, here's how to reset your password...",
    tokens_used=250,
    prompt_tokens=100,
    completion_tokens=150,
    cost=0.005,  # Optional, in USD
    duration_ms=1200
)

# Returns: str (event_id)

track_error

Track errors that occur during agent execution.

client.track_error(
    session_id=session_id,
    error_type="APIError",
    error_message="Knowledge base API timeout",
    stack_trace="Traceback (most recent call last):\n...",
    recoverable=True,
    recovery_action="Retry with fallback search"
)

# Returns: str (event_id)

SentrialCallbackHandler

LangChain callback handler for automatic tracking.

from sentrial import SentrialClient, SentrialCallbackHandler

client = SentrialClient(api_key="...", project_id="...")
session_id = client.create_session(name="My Agent")

# Create handler
handler = SentrialCallbackHandler(
    client=client,
    session_id=session_id,
    verbose=True,  # Optional, print tracking events
    track_chain_of_thought=True,  # Optional, track intermediate steps
    track_tool_errors=True  # Optional, track tool failures
)

# Use with LangChain
from langchain.agents import AgentExecutor

agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    callbacks=[handler]
)

result = agent_executor.invoke({"input": "Help the user"})

What gets tracked automatically:

Agent reasoning and chain of thought
Tool calls (inputs, outputs, and errors)
LLM calls (prompts, responses, token usage)
Agent completion status

Type Definitions

The SDK includes TypedDict definitions for all data structures:

from sentrial.types import (
    Session,
    Event,
    ToolCall,
    Decision,
    LLMCall,
    ErrorEvent
)

# All SDK methods accept and return typed dictionaries
# for better IDE support and type checking

Examples

Check out complete examples in the repository: