AI agents and human handoff (HITL)

FluxyChat supports Intercom-Fin-style flows: an in-room AI agent responds until a human operator takes over. Handoff pauses AI invokes, enqueues an agent task with thread context, and resumes AI when the handoff completes.

Architecture

sequenceDiagram
  participant User
  participant Room as Room WS
  participant AI as AI Agent
  participant Queue as Agent queue
  participant Human as Human operator

  User->>Room: message
  Room->>AI: invoke (if no active handoff)
  AI->>Room: reply
  Human->>Room: POST handoff (take over)
  Room->>Queue: create + claim task
  Note over AI: invoke blocked (409)
  Human->>Room: resolve handoff + disposition
  Room->>AI: invoke allowed again

API

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

SDK

import { FluxyChatClient } from "@fluxy-chat/sdk";

const client = new FluxyChatClient({ baseUrl, userId, token });

const { handoff } = await client.getRoomHandoff(roomId);

await client.requestRoomHandoff(roomId, {
  agentId: "support_lead",
  note: "VIP customer — billing issue",
});

await client.resolveRoomHandoff(roomId, "resolved");

While handoff is active, POST /agents/:id/invoke and @mention agent invokes return 409 human_handoff_active.

Dashboard

Configure agents under Agents (/agents). Each agent has model, system prompt, tools, and room allowlist.

Configure an in-room agent

1. Create agent in dashboard → copy agent id
2. Bind to room via project settings or @agent mention rules
3. Test invoke: POST /agents/{id}/invoke with { "roomId": "…", "prompt": "…" }

Human-in-the-loop patterns

Database

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

Related

• Agent queue — SLA, dispositions, wrap-up
• Custom tools — tools the agent can call
• Thread state — per-thread KV for agent memory