# Human handoff

Pass a thread from the agent to a person, and between people, without losing where it stands.

For: Customers and the staff who take over.

Web page: https://candor.themethodic.com/screens/human-handoff

## Layouts

### In the customer's thread

Pick it when: The customer should see that a person has taken over and that the agent has stopped replying.

Layout: A thread with a quiet event line saying a person joined, then a person's message and the composer.

Items:

- **Thread event** (`thread-event`, free; https://candor.themethodic.com/docs/thread-event.md): "Sam joined": a quiet line for something that happened.
- **Agent avatar** (`agent-avatar`, free; https://candor.themethodic.com/docs/agent-avatar.md): Tells the agent's messages from a person's at a glance.
- **Thread** (`thread`, free; https://candor.themethodic.com/docs/thread.md): The conversation, with the agent silent after the handoff.
- **Composer** (`composer`, free; https://candor.themethodic.com/docs/composer.md): Now the customer talks to a person.

```bash
npx candor-ui add thread-event agent-avatar thread composer
```

### Handoff queue for staff

Pick it when: Staff pick up handed-off threads and need the context at once.

Layout: A queue of handed-off threads on the left, with the selected thread and its handoff card on the right.

Items:

- **Handoff card** (`handoff-card`, Pro; https://candor.themethodic.com/docs/handoff-card.md): Who from, who to, where the run is, what's needed next.
- **Inbox** (`inbox`, Pro; https://candor.themethodic.com/docs/inbox.md): The threads that need a person, by what they need.
- **Human handoff** (`human-handoff`, Premium; https://candor.themethodic.com/docs/human-handoff.md): The full-stack block: the agent decides, the thread moves, the agent stops.

```bash
npx candor-ui add handoff-card inbox human-handoff
```

### Escalate outside the app

Pick it when: The person who has to act isn't in the app: someone on call is paged, a team is emailed, or a ticket is opened in another system.

Layout: The thread on the left; on the right the ways to escalate, each with who it reaches now, and the exact message to be sent under them.

Items:

- **Escalation** (`escalation`, Pro; https://candor.themethodic.com/docs/escalation.md): A page, an email or a ticket: who each way reaches now, exactly what will be sent and to whom, then a record of what went and whether anyone acknowledged it.
- **Handoff card** (`handoff-card`, Pro; https://candor.themethodic.com/docs/handoff-card.md): The handoff inside the app, when a person here takes the thread instead.
- **Thread** (`thread`, free; https://candor.themethodic.com/docs/thread.md): The conversation the escalation is about.

```bash
npx candor-ui add escalation handoff-card thread
```

## Rules that matter most here

- **The agent is always named, by the app** (https://candor.themethodic.com/principles#agents-are-named): The thread says who is answering, a person or the agent, from your app's records.
- **Unknown stays unknown** (https://candor.themethodic.com/principles#unknown-stays-unknown): A handoff with nobody picking it up shows as waiting, with how long, not as handled.
- **Say what can and can't be undone** (https://candor.themethodic.com/principles#say-what-can-be-undone): Handing back to the agent says whether the agent will see what the person wrote.

A full-stack block builds this with an agent route and a store: `human-handoff` (https://candor.themethodic.com/docs/human-handoff.md). Each block has a `-claude` twin for the Claude Agent SDK.

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
Build a human handoff with Candor UI: the agent answers a customer and passes the thread to a person when it should.
Start from the human-handoff block (human-handoff-claude for the Claude Agent SDK): the agent decides, the thread moves, the agent stops replying, and the customer's thread says so.
In the thread, show the handoff as a ThreadEvent and tell the agent's messages from a person's with AgentAvatar.
For staff, list handed-off threads in an Inbox and show each with a HandoffCard: who from, who to, where it stands and what's needed next.
A thread nobody has picked up shows as waiting with how long it has waited; never as handled.
Name who is answering from your app's records, not from model output.
When a person hands back to the agent, say plainly what the agent will and won't see.
When the person who has to act isn't in the app, use Escalation: no way is chosen for the person, the message an agent drafted says so and can be edited, and only what your server records as sent is shown as sent.

Start from the "In the customer's thread" layout: A thread with a quiet event line saying a person joined, then a person's message and the composer.
Candor items: thread-event (https://candor.themethodic.com/docs/thread-event.md), agent-avatar (https://candor.themethodic.com/docs/agent-avatar.md), thread (https://candor.themethodic.com/docs/thread.md), composer (https://candor.themethodic.com/docs/composer.md).
Install: npx candor-ui add thread-event agent-avatar thread composer
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.
```