Handoffs

Pass it on

Implement the Handoffs pattern in this codebase, using the LLM client and language we already use.

## Goal

Let a user talk directly to whichever specialist agent fits the conversation, by passing one shared message history between agents through handoff tool calls, with no manager in the middle.

## How it works

1. Define each agent with its instructions, its own tools, and one handoff tool for each agent it may transfer to, such as transfer_to_billing, each taking a one-sentence goal.
2. Keep one message history per conversation and an active-agent pointer that starts at the triage agent, which runs with the Triage agent instructions.
3. On each user message, call the active agent with the full history.
4. If it calls a handoff tool, append the handoff and its goal to the history, move the pointer to the target agent, and call that agent, with the Specialist agent instructions, on the same history in the same turn.
5. If it replies without handing off, send the reply to the user; the pointer stays where it is for the next message.

## Prompts

### Triage agent instructions

```markdown
You are the front desk for {{company}}. Greet the user and work out what
they need. Do not try to solve the problem yourself.

Hand off with exactly one tool:
- transfer_to_billing: charges, invoices, plans
- transfer_to_tech: errors, bugs, how-to questions
Before you hand off, state the user's goal in one sentence so the next
agent does not have to ask again.
```

### Specialist agent instructions

```markdown
You are the {{role}} agent for {{company}}. You now own this conversation.
The full history above is yours to read.

Help the user directly. If the request belongs to another agent, hand off
with {{handoff_tools}} and say what you are passing on.
Never ask the user to repeat something already in the history.
```

## Stop rule

A turn ends when the active agent replies to the user. Allow at most 3 handoffs per user message; on the cap, send a short apology and route the conversation to a human.

## Requirements

- Make the per-message handoff cap a parameter (default 3), to stop two agents passing the user back and forth.
- Treat a handoff to an unknown or disallowed agent as a tool error returned to the calling agent, not a crash.
- Require the goal argument; if it is empty, return a tool error asking the agent to state the user's goal.
- Log every handoff with the agent it came from, the agent it went to, and the goal.
- Add a test with a stub LLM where triage hands off to billing and billing hands off to refunds, which replies; assert the pointer ends at refunds and exactly two handoffs were logged.

Hand back

Implement the Handoffs pattern (Hand back variant) in this codebase, using the LLM client and language we already use.

## Goal

Serve a request that spans several specialists by letting each one hand the conversation back to triage when its part is done, so triage can route the rest.

## How it works

1. Give triage, which runs with the Triage agent instructions, one handoff tool per specialist; give every specialist, which runs with the Specialist agent instructions, a transfer_back_to_triage tool that takes a summary of what is done and what is left.
2. Keep one message history and an active-agent pointer that starts at triage; call the active agent with the full history on each user message.
3. When an agent calls a handoff tool, append the handoff and its argument to the history, move the pointer, and call the new agent in the same turn. An agent may send the user a message and call a handoff tool in one response: send the message, then follow the handoff.
4. When a specialist hands back, triage reads the summary and either hands the open part to another specialist or replies to the user.
5. Send whichever agent's reply ends the turn to the user.

## Prompts

### Triage agent instructions

```markdown
You are the front desk for {{company}}. Work out what the user needs.
Do not try to solve the problem yourself.

Hand off with exactly one tool:
- transfer_to_billing: charges, invoices, plans
- transfer_to_tech: errors, bugs, how-to questions
State the user's goal in one sentence when you hand off.

When a specialist hands the conversation back, read its summary. If
something is still open, hand that part to the right specialist;
otherwise ask the user whether there is anything else.
```

### Specialist agent instructions

```markdown
You are the {{role}} agent for {{company}}. You now own this conversation.
The full history above is yours to read.

Help the user with the part that is yours. When it is done, or if the
rest belongs to someone else, call transfer_back_to_triage with a
summary: what you did, and what is still open.
Never ask the user to repeat something already in the history.
```

## Stop rule

A turn ends when the active agent replies to the user without calling a handoff tool; a message sent together with a hand-back does not end it. Allow at most 4 handoffs per user message, hand-backs included; on the cap, apologize and route the conversation to a human.

## Requirements

- Make the per-message handoff cap a parameter (default 4).
- Require a non-empty summary on transfer_back_to_triage; if it is empty, return a tool error asking for one.
- Stop triage from handing straight back to the agent that just handed back with no new user message; return a tool error instead, to prevent ping-pong.
- Log every handoff and hand-back with its from, its to and its argument.
- Add a test with a stub LLM where triage hands off to billing, billing hands back saying 'refund done; crash still open', and triage hands off to tech; assert the pointer visits triage, billing, triage, tech in that order.

Remembers active agent

Implement the Handoffs pattern (Remembers active agent variant) in this codebase, using the LLM client and language we already use.

## Goal

Keep a multi-turn conversation with the specialist the user was last talking to, by storing the active agent per conversation and starting each new message there instead of at triage.

## How it works

1. Keep a store keyed by conversation id that holds the active agent's name; a new conversation starts at triage, which runs with the Triage agent instructions.
2. On each user message, load the active agent from the store and call it with the full history.
3. When an agent calls a handoff tool, write the target agent to the store first, then call the target, with the Specialist agent instructions, on the same history in the same turn.
4. Send the reply that ends the turn to the user; the stored agent stays active for the next message.
5. Have specialists hand back to triage when the user changes topic, which writes triage to the store.

## Prompts

### Triage agent instructions

```markdown
You are the front desk for {{company}}. Greet the user and work out what
they need. Do not try to solve the problem yourself.

Hand off with exactly one tool:
- transfer_to_billing: charges, invoices, plans
- transfer_to_tech: errors, bugs, how-to questions
Before you hand off, state the user's goal in one sentence so the next
agent does not have to ask again.
```

### Specialist agent instructions

```markdown
You are the {{role}} agent for {{company}}. You now own this conversation.
The full history above is yours to read.

Help the user directly. If the request belongs to another agent, hand off
with {{handoff_tools}} and say what you are passing on.
Never ask the user to repeat something already in the history.
```

## Stop rule

A turn ends when the active agent replies. Allow at most 3 handoffs per message; on the cap, reply with an apology and route to a human.

## Requirements

- Persist the store so a restart does not send every user back to triage.
- If the stored agent no longer exists, fall back to triage and log it.
- Reset the active agent to triage after a configurable idle time (default 30 minutes).
- Write the store before calling the new agent, so a crash mid-turn resumes with the right agent.
- Add a test with a stub LLM: on message 1 triage hands off to billing; on message 2 assert triage is never called and billing is called first.