AgentRetrieval
One data retrieval an agent performed inside an AgentSession — which tool ran, what it was asked, and whether anything came back.
Purpose
Section titled “Purpose”Agent surfaces (voice, MCP clients, Claude, ChatGPT, Gemini) call tools that read organisation data. Each qualifying call is recorded here so retrieval activity can be attributed to a user, an organisation and a credit. project_id records the credit or corpus touched; the object_type/object_id pair records the primary object returned, such as a focus individual.
Rows are written by the agent session tracker as tools execute, and read back for reporting.
app/Services/Agents/AgentSessionTracker.php— records retrievals as tools runapp/Http/Controllers/AgentsController.php— agent activity reportingapp/Http/Controllers/Voice/VoiceTokenController.php— voice session bootstrapapp/Services/Voice/Tools/GetAgentsActivity.php— voice tool exposing recent activity
Relationships
Section titled “Relationships”| Relation | Type | Related model |
|---|---|---|
session |
belongsTo |
AgentSession |
organization |
belongsTo |
Organization |
user |
belongsTo |
User |
project |
belongsTo |
Project |
Data shape
Section titled “Data shape”Table: agent_retrievals
| Column | Type | Notes |
|---|---|---|
id |
uuid |
Primary key |
agent_session_id |
uuid |
FK agent_sessions, cascade delete |
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 |
tool_name |
string |
Tool that performed the retrieval |
page |
string |
Nullable, originating page |
project_id |
uuid |
Nullable, FK projects, null on delete |
object_type |
string |
Nullable, primary object class |
object_id |
string |
Nullable, primary object key |
query |
text |
Nullable, the query issued |
outcome |
RetrievalOutcome |
returned or abstention |
created_at, updated_at |
timestamp |
Nullable |