Pattern: human–agent handoffs
Hand work between people and agents through the ledger instead of chat history.
Who it's for
Anyone whose work outlasts one session. For example, a developer who hands a half-finished investigation to a colleague, an on-call engineer at shift change, or a person who asks an agent to pick up where they stopped.
Why a topic, not a transcript
A chat transcript belongs to one session. It's long, it mixes dead ends with conclusions, and the next person or agent may not be able to open it.
A ledger topic is durable, searchable and attributed. Its current state says where things stand, in one place. Its history keeps every step, with the person and agent behind each one.
How a handoff works today
- The outgoing person asks their agent to bring the topic up to date. If there's no topic yet, the agent creates one. It sets the current state to where things stand, including the next step.
- They pass on the topic id, or the link from Copy link on the topic's page in the console, through whatever channel your team uses.
- The incoming person or agent reads the topic with
ledger_get, or on the console's Ledger page, and continues from the next step. - The incoming side appends as it works, and updates the current state when it stops or hands on again.
- When the work ends, the agent sets the final state and a closing status, such as resolved or accepted.
People write to the ledger through their agents. The console shows the ledger but doesn't edit it.
What a good handoff topic contains
| Part | What to put there |
|---|---|
| Title | The problem, not the activity: "Export times out for large accounts", not "Friday debugging". |
| Summary | The original framing. It's fixed when the topic opens. |
| Current state | Where it stands, what's done, the next step, open questions and blockers. |
| Evidence | Citations: repository, path and line range, page, issue key, related topic ids. |
| Type and status | An open investigation or incident, or a proposed decision, until the work ends. |
A current state that fits on one screen works best. For example:
text
Where it stands: timeouts reproduce on accounts with over 200,000 rows, not on smaller ones.
Done: ruled out the database (query plans in export-0004); confirmed the worker's 60-second limit.
Next step: stream the export in pages instead of building it in memory (exports/worker.py:88-140).
Open questions: can the limit rise without a plan change? Asked product.
Evidence: SUP-1423, export-0004, exports/worker.py:88-140Prompts for both sides
The prompts are illustrative. For the outgoing side:
text
Update the current state of export-0007 for a handoff: what we tried, what worked, the next step and open questions, with citations. Keep it under 150 words.For the incoming side:
text
Get export-0007 from the ledger. Summarise where it stands, then continue from the next step. Append what you do as you go.An illustrative example
Illustrative
At 6 p.m. in Sydney, a developer's agent updates export-0007 with the next step and an open question for product. At 9 a.m. in London, a colleague asks their own agent to pick it up.
The agent reads the topic, skips the two approaches already ruled out and starts on the next step. It appends its progress as it goes. The developer in Sydney sees what changed overnight without a meeting or a message thread.
Limits to know
- You pass on the topic yourself. Workstate doesn't notify anyone. Addressed handoffs Coming soon, briefings when a session starts Coming soon and subscriptions Coming soon aren't available yet.
- Both sides need access to the same namespace.
- The current state is one text field. Keep it short, and let the history hold the detail.