Screens / Talking to the agent

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.

Markdown

3 ways to lay it out

1. 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.

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

Thread eventFree"Sam joined": a quiet line for something that happened.
Agent avatarFreeTells the agent's messages from a person's at a glance.
ThreadFreeThe conversation, with the agent silent after the handoff.
ComposerFreeNow the customer talks to a person.

Install in the customer's thread

2. Handoff queue for staff

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

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

Handoff cardProWho from, who to, where the run is, what's needed next.
InboxProThe threads that need a person, by what they need.
Human handoffPremiumThe full-stack block: the agent decides, the thread moves, the agent stops.

Install handoff queue for staff

Pro and Premium items need a licence key; free ones install as they are.

3. 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.

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.

EscalationProA 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 cardProThe handoff inside the app, when a person here takes the thread instead.
ThreadFreeThe conversation the escalation is about.

Install escalate outside the app

Pro and Premium items need a licence key; free ones install as they are.

Rules that matter most here

The agent is always named, by the app
The thread says who is answering, a person or the agent, from your app's records.
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
Handing back to the agent says whether the agent will see what the person wrote.

Already covered elsewhere

Builds the whole screen with an agent route and a store: Human handoff (Premium), with a -claude twin for the Claude Agent SDK.

Brief for a coding agent

Paste this into the agent that builds the screen. The docs MCP server returns the same text from get_screen.

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.