AI agent and human handoff

An in-room AI agent can respond until a human operator takes over. Handoff pauses AI invokes, enqueues an agent task with thread context, and resumes AI when the handoff is completed with a disposition code.

API

Disposition codes: GET /agent-queue/dispositions (shared with agent queue wrap-up).

Behaviour

1. Take over: builds a context summary from the last 12 messages, creates and auto-claims an agent queue task (trigger_source=ai_handoff), inserts room_handoffs row (human_active), broadcasts type: handoff on the room WebSocket.
2. While active: POST /agents/:id/invoke and @mention agent invokes return 409 human_handoff_active.
3. Complete: PATCH with disposition resolves the handoff and linked agent task; AI can respond again.

Dashboard

• Agent room chat: AgentHandoffBanner (Take over / Complete handoff plus context preview).
• Agent queue: /agent-queue with disposition picker and resolved stats.

SDK

const { handoff } = await client.getRoomHandoff(roomId);
await client.requestRoomHandoff(roomId, { agentId, note: "VIP customer" });
await client.resolveRoomHandoff(roomId, "resolved");

Database

• Migration 0056_room_handoffs.sql
• Links to agent_tasks via agent_task_id

Related

• Agent queue for SLA timers and dispositions
• Telephony handoff for voice and SMS escalation