Hand-off
When the agent should stop, a person takes over.
Every thread has an owner — a person, an agent or an automation. Change it in one call, and the agent is told, steps back, and picks up again when the thread is handed back.
On every plan. The other side sees one conversation, from one address.
01 · How it works
4 steps.
01 · The agent gives it up
When a conversation needs a person, one request makes it theirs and puts it in the queue. thread.updated tells everything watching.
curl https://pidgeon.ai/api/v1/threads/$THREAD_ID \ -X PATCH \ -H "Authorization: Bearer $PIDGEON_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "owner_type": "human", "status": "human_review" }'02 · A person takes it
In the inbox the thread says Waiting for a person, with a Take it button beside it. Pressing it fires thread.assigned, so your software knows who has it.
03 · They reply, as the address
From the web client, in the same thread, from the agent’s own address. The other side sees a reply to their email and nothing else.
04 · And back again
One more request returns the conversation to the agent, which carries on where it left off.
curl https://pidgeon.ai/api/v1/threads/$THREAD_ID \ -X PATCH \ -H "Authorization: Bearer $PIDGEON_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "owner_type": "agent", "status": "open", "assignee_id": null }'
02 · What it does
Why hand-off works this way.
Ownership is state
Who has a conversation is a field on the thread, not a flag in your process — so every tool reading the thread agrees on it.
One address throughout
The person answers from the agent’s address, in the same thread. A hand-off that changes the address is a transfer, and costs the other side a new thread.
Events, not polling
thread.updated and thread.assigned are subscribable, so a hand-off can post to Slack, open a ticket or wake your process.
03 · Questions
Asked before trusting it.
- How is a hand-off different from an approval queue?
- In an approval queue the software is still answering and a person checks its work. In a hand-off a person has the conversation: the software has stepped back and is not drafting anything, and everything watching has been told.
- Does the other side know a person took over?
- No. The person replies from the same address, in the same thread, with the same headers, so the other side sees one conversation throughout.
- Does Pidgeon decide when to hand a thread over?
- No. There is no model and no loop in it: your agent, or your code, decides, and Pidgeon makes the change of hands a single request that everything else can see.
04 · More