> ## Documentation Index
> Fetch the complete documentation index at: https://www.sentrial.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions & Tracking

> Sessions are the foundation of Sentrial. Every agent interaction is a session — a complete record of what happened, when, and why.

## What is a Session?

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

<CardGroup cols={2}>
  <Card title="Timeline">
    When the interaction started and ended, plus duration.
  </Card>

  <Card title="User Context">
    Which user triggered the interaction.
  </Card>

  <Card title="Events">
    Every LLM call, tool usage, and decision in sequence.
  </Card>

  <Card title="Outcome">
    Whether the session succeeded or failed, plus metrics.
  </Card>
</CardGroup>

## Creating Sessions

### Simple API (Recommended)

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

```python theme={null}
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:

```python theme={null}
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.)

```python theme={null}
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:

```python theme={null}
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

<Note>
  **LangChain Integration** — If you use LangChain, our callback handler automatically tracks all events. No manual tracking needed.
  [Learn more about LangChain integration →](/integrations/langchain)
</Note>

```python theme={null}
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

<Steps>
  <Step title="Created">
    Session starts when agent begins processing.
  </Step>

  <Step title="Events">
    Tool calls, decisions, and LLM calls are tracked.
  </Step>

  <Step title="Completed">
    Session ends with success/failure status and metrics.
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Issues & Diagnosis" icon="magnifying-glass" href="/concepts/diagnosis">
    Learn how issues are automatically detected.
  </Card>

  <Card title="Python SDK Reference" icon="python" href="/sdk/python">
    Complete API for session tracking.
  </Card>
</CardGroup>