AgentSession

A single agent conversation or session, together with duration, response count and token usage.

Purpose

Every agent surface reports sessions in the same shape. Voice was the first, with MCP clients, Claude, ChatGPT, Copilot and Gemini reporting the same structure. The session is the parent record for the individual retrievals an agent made, and carries the accounting used for usage and cost reporting.

Usage

Sessions are opened and closed by the tracker, then surfaced in reporting and admin.

app/Services/Agents/AgentSessionTracker.php — opens, updates and closes sessions
app/Http/Controllers/Voice/VoiceSessionController.php, VoiceTokenController.php, VoiceToolController.php — voice session lifecycle
app/Mcp/Support/McpSessionResolver.php — resolves the session for MCP tool calls
app/Filament/Pages/VoiceSessions.php — staff-facing session listing
app/Http/Controllers/AgentsController.php — agent activity page

Relationships

Relation	Type	Related model
`organization`	`belongsTo`	Organization
`user`	`belongsTo`	User
`retrievals`	`hasMany`	AgentRetrieval

Data shape

Table: agent_sessions

Column	Type	Notes
`id`	`uuid`	Primary key
`organization_id`	`uuid`	Nullable, FK `organizations`, null on delete
`user_id`	`uuid`	Nullable, FK `users`, null on delete
`agent_type`	`AgentType`	voice, mcp, claude, chatgpt, copilot, gemini
`client_session_id`	`string`	Nullable, upstream provider session id
`client_name`	`string`	Nullable, reporting client
`started_at`	`datetime`	Session start
`ended_at`	`datetime`	Nullable
`duration_seconds`	`integer`	Nullable
`ended_reason`	`string`	Nullable
`responses`	`integer`	Defaults to 0
`input_tokens`, `input_text_tokens`, `input_audio_tokens`	`integer`	Default 0
`input_cached_text_tokens`, `input_cached_audio_tokens`	`integer`	Default 0
`output_tokens`, `output_text_tokens`, `output_audio_tokens`	`integer`	Default 0
`total_tokens`	`integer`	Default 0
`created_at`, `updated_at`	`timestamp`	Nullable