AgentDeskStore), and agent-desk policy module. Queue state lives in Redis (request.app.state.agent_desk_store); completed call records land in the calls collection with call_type: "agent".
Authentication
The route uses three auth surfaces:| Surface | Used for |
|---|---|
X-CXB-Core-Secret (_verify_core_secret) | CXB Core → CXB API ingress: /enqueue, transcript/recording/event updates, customer-disconnected |
require_agent_or_supervisor | Agent-facing queue, call accept/reject/end, status |
require_supervisor | Supervisor monitoring and force-end |
Endpoint groups
/api/v1/agent-desk (selected — the router exposes ~28 routes):
| Group | Endpoints | Purpose |
|---|---|---|
| Enqueue | POST /enqueue | CXB Core hands a waiting call to the queue (call_id, room, caller, bot, escalation_reason, transcript, variables, context) |
| Queue | GET /queue, GET /queue/stream (SSE) | Agent-scoped waiting list and live updates |
| Call lifecycle | POST /calls/{id}/accept · reject · decline · end · hangup · customer-disconnected | Agent handling |
| Call state | GET /calls/{id}/state, GET /calls/current, GET /calls/{id} | State reads |
| Call updates | POST /calls/{id}/events · transcript · recording | CXB Core-driven updates |
| Agent status | POST /status · status/heartbeat · status/offline, GET /status | Presence (available/away/busy) |
| Supervisor | GET /supervisor/dashboard · supervisor/stream, POST /supervisor/calls/{id}/listen · barge-in · force-end | Monitoring + intervention |
| Metrics | GET /metrics, GET /me/metrics | Day-bucketed metrics (uses display timezone) |
create_agent_token, create_supervisor_listen_token = subscribe-only, create_supervisor_barge_token = full publish).
Queue flow
On enqueue, if a transcript is supplied CXB API fires a background summary generation task (_generate_summary) — using a module-level cached LLM client to avoid the LLM client SDK’s per-instantiation memory leak.
Timeout & decline policy
The agent-desk policy module runsrun_agent_desk_policy_loop as a background task started at application startup:
| Knob | Source | Default |
|---|---|---|
timeout_seconds | settings.agent_desk_waiting_timeout_seconds | 120 |
poll_seconds | settings.agent_desk_policy_poll_seconds | 5 |
- Timeout (
enforce_waiting_timeouts): calls waiting longer thantimeout_secondsare ended with eventagent_desk_timeout,disconnected_by="no_agent", dispositionNo Agent Available. - All available declined (
terminate_if_all_available_agents_declined): if every currentlyavailableagent/supervisor has declined a call, it is ended with eventall_agents_declined.
terminate_waiting_call atomically claims the call (claim_waiting_call_for_termination), tears down the LiveKit room (remove_all_participants), writes a call_type: "agent" record (idempotent upsert keyed by parent_call_id), and marks it ended. If teardown fails, the call is restored to waiting (and declines optionally cleared) rather than lost.
Related docs
Transfer & escalation (CXB Core)
How CXB Core decides to escalate and calls
/enqueue.Agent Assist
Live suggestions for agents handling escalated calls.
Users & roles
Agent/supervisor roles and presence.
Settings
Display-timezone day boundaries used by metrics.