Agents

Purpose

Describe agents: their state machine, how presence is tracked, and how occupancy is measured.

Overview

Agents (agents table) are tenant users who handle calls. An agent is always in one of five states (enforced by a pure transition function and a DB CHECK):

offline, available, busy, wrap-up, break.

The key transitions:

stateDiagram-v2
  [*] --> offline
  offline --> available: login
  available --> busy: call_assigned
  available --> break: break_start
  busy --> wrap-up: hangup
  wrap-up --> available: wrap_up_complete
  wrap-up --> break: break_start
  break --> available: break_end
  available --> offline: logout
  busy --> offline: logout / force_offline

A hangup goes to wrap-up (not straight to available) so the agent can set a disposition. Each completed interval is written to agent_state_intervals (migration 054), which is the source for time-in-state and occupancy reporting.

Configuration

Agents work in the tenant app with a browser WebRTC softphone over WSS. Their skills (a TEXT[]) and queue memberships determine which calls they receive. Presence is a Redis hot path with a 180s TTL refreshed by a heartbeat; a lapsed entry is shown as offline, and a heartbeat-expiry sweeper emits force_offline.

Examples

A typical lifecycle: available → busy → wrap-up → available. On the busy → wrap-up transition the engine credits handle time and closes the busy interval, and publishes the change to t.<tenant>.agent.<id>.state for the supervisor dashboard.

Occupancy is computed from the interval log as:

occupancy = (busy_secs + wrap_secs) / (available_secs + busy_secs + wrap_secs)

Notes

State, handle time and occupancy come from the durable interval log; the agents row only holds the current point-in-time state.
Skills gate queue selection only under the skills_based strategy — see Skills.