Trident

Sessions & Checkpoints

When sessions are enabled for an agent, each run creates an AgentSession record and periodically writes SessionCheckpoint rows containing snapshots of state and conversation.

Enabling sessions

Sessions are enabled per-agent by passing both organizationId and enableSessions: true to the agent constructor.

import { SERPAnalysisAgent } from "@/lib/agents";

const agent = new SERPAnalysisAgent({
  organizationId: "org_123",
  enableSessions: true,
});

const result = await agent.run({
  keyword: "example",
  market: "us",
  territoryId: "territory_1",
});

Statuses

Sessions use the AgentSessionStatus enum in the database.

  • active: currently running or resumable
  • paused: paused and resumable
  • completed: run finished successfully
  • failed: run failed
  • expired: TTL passed; resumptions should be rejected

TTL + cleanup

Sessions have an expiresAt timestamp (default TTL is 24 hours). A cleanup job deletes expired sessions; checkpoints are deleted automatically via cascade.

What a checkpoint contains

Each checkpoint stores:

  • stateSnapshot: JSON snapshot of the agent AgentState
  • conversationSnapshot: JSON snapshot of the agent conversation (if provided)
  • step: label like step_3 or a custom step name

Important notes

  • Resumes are per-agent: the E-E-A-T pipeline orchestrator enables sessions for its underlying stage agents. You may see multiple sessions created during a pipeline run.
  • Tenant scoping: sessions are always loaded using both id and organizationId.