Agent KPIs

Agent KPIs are computed by the per-account PresenceDO directly from its agent-state event log (agent_event). Because every state transition is already recorded durably, the metrics are a pure function of that log over a time window, so there’s no separate metrics pipeline to keep in sync.

All KPIs take a since timestamp (epoch ms) and report over the window [since, now].

State-time

For each agent, the brain walks agent_event in order and sums the time spent in each bucket. The duration of a transition into bucket S at ts[i] runs until the next transition ts[i+1], or until now for the most recent one:

statusMs = { ready: …, incall: …, wrapup: …, paused: …, idle: …, … }   // ms per bucket
loggedInMs = Σ statusMs   excluding `offline`

statusMs is the raw building block; loggedInMs is total time logged in (everything except offline).

Occupancy

Occupancy answers “while available, how much of the time was the agent actually working a call?” It’s a measure of how hard staffed agents are being worked.

handle      = incall + wrapup
occupancyPct = round( 100 × handle / (handle + ready) )      // 0 if denominator is 0

The denominator is handle + ready: productive time plus time sitting idle-but-available. Time paused, offline, or unreachable is excluded entirely, so occupancy isolates “of the time you were on the floor ready to work, what fraction was spent on calls.”

Utilization

Utilization answers “of the agent’s whole logged-in shift, how much was spent handling calls?” It’s handle time against everything except being logged out.

utilizationPct = round( 100 × handle / loggedInMs )          // loggedInMs excludes offline

Because the denominator includes paused and idle time, utilization ≤ occupancy for the same agent over the same window. Occupancy measures intensity while ready; utilization measures share of the whole shift.

Reading the report

Agent KPIs are read from the public API at GET /v1/agents (the agents scope):

curl 'https://api.sip.io/v1/agents?since=1719500000000' -H 'x-api-key: sk_…'

{
  "agents": [
    {
      "user_id": "1001",
      "statusMs": { "ready": 5400000, "incall": 2700000, "wrapup": 300000, "paused": 600000 },
      "loggedInMs": 9000000,
      "occupancyPct": 35,
      "utilizationPct": 33,
      "adherencePct": 92
    }
  ]
}

adherencePct is included when the agent has a work schedule; see that page for its meaning and the null / "bypass" cases.

Roadmap

• Raw-event export: periodic flush of agent_event to the data lake for ad-hoc and historical analysis beyond the live window.
• Per-segment activity breakdown: splitting paused into break/lunch/training for finer occupancy and shrinkage reporting.