# Hand off a conversation

A user asks your support agent for a refund. The support agent cannot do refunds, but your billing agent can. Then the user wants a person, and a person from your team must take over. Later, the whole case must move to the harness of another team.

A handoff moves the conversation to another agent or to a person. A transfer moves it to another thread, also of another harness. In both cases, control moves on purpose, and only the data that you name moves with it.

## 1. Let agents hand off

Give the harness its root agents and `routing`. A router that returns `undefined` lets the agent that answers now keep the turn:

```ts group=harness-handoffs
import { defineAgent } from '@tanstack/ai'
import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
import { memoryPersistence } from '@tanstack/ai-persistence'
import { openaiText } from '@tanstack/ai-openai'

const billing = defineAgent({
  name: 'billing',
  description: 'Handles refunds, invoices, and payments',
  run: (ctx) =>
    ctx.chat({
      adapter: openaiText('gpt-6.1-sol'),
      systemPrompts: ['You handle refunds, invoices, and payments.'],
    }),
})

export const support = defineHarness({
  name: 'acme/support',
  adapter: openaiText('gpt-6.1-sol'),
  systemPrompts: ['You are the support desk. Hand billing questions to billing.'],
  agents: [billing],
  routing: { router: () => undefined },
})

export const host = createHarnessHost({ persistence: memoryPersistence() })

export async function ask(threadId: string, text: string) {
  const session = await host.open(support, { threadId })
  return session.send(text)
}
```

Send `I want a refund for order 42.` The main model calls its `handoff` tool with `{ to: 'billing', note }`. Then billing answers in the same turn. The turn text is `billing:\n...`.

What the handoff does:

- The log keeps the active agent. Later turns go to billing until it hands off again, or until the router picks another agent.
- The main model and each root agent get a `handoff` tool. Its `to` lists the root agents. A root agent can also hand back to `'main'`, the main model. A whole harness in `agents` can hand back too. See [Make a harness a root agent](./subagents#make-a-harness-a-root-agent).
- One turn can hand off 10 times at most.
- An agent that is only in `subagents` cannot be a target. A child that an agent starts cannot hand off either.
- An app tool named `handoff` replaces the harness tool. See [Use your own handoff tool](#use-your-own-handoff-tool). To give no model the `handoff` tool, set `routing: { router, giveModelsHandoffTool: false }`. The router and your code can still hand off.

### Use your own handoff tool

The `handoff` tool takes only `to` and a short `note`. The target then often asks the user again for facts that the first agent had. Pass `routing.handoffTool` to set the description, the fields, and the note of the tool:

```ts
import { defineAgent, toolDefinition } from '@tanstack/ai'
import { defineHarness } from '@tanstack/ai-harness'
import { openaiText } from '@tanstack/ai-openai'
import { z } from 'zod'

const billing = defineAgent({
  name: 'billing',
  description: 'Handles refunds, invoices, and payments',
  run: (ctx) =>
    ctx.chat({
      adapter: openaiText('gpt-6.1-sol'),
      systemPrompts: ['You handle refunds, invoices, and payments.'],
    }),
})

export const support = defineHarness({
  name: 'acme/support',
  adapter: openaiText('gpt-6.1-sol'),
  agents: [billing],
  routing: {
    router: () => undefined,
    handoffTool: ({ from, targets, handoff }) =>
      toolDefinition({
        name: 'handoff',
        description: 'Hand the user to another agent. Say what you did and what the user still needs.',
        inputSchema: z.object({
          to: z.enum(targets),
          done: z.string().describe('What you did for the user'),
          next: z.string().describe('What the user still needs'),
          orderId: z.string().optional(),
        }),
      }).server(async ({ to, done, next, orderId }) => {
        const order = orderId ? ` Order: ${orderId}.` : ''
        await handoff({ to, note: `From ${from ?? 'main'}. Done: ${done}. Next: ${next}.${order}` })
        return `Handed off to ${to}.`
      }),
  },
})
```

- The harness calls `handoffTool` once per turn for each speaker: the main model (`from: null`) and each root agent.
- `targets` holds the names that this speaker can hand off to. `allowHuman` is the value of `routing.allowHandoffToHuman`.
- `handoff({ to, note })` hands off. For the main model, the tool call is already in the transcript. The harness adds no note messages.
- A tool handoff from a root agent still adds the two note messages.
- The tool can have any name. With `giveModelsHandoffTool: false`, the harness does not call `handoffTool`.

Give one speaker an app tool with the same name as the tool that `handoffTool` returns. It replaces the harness tool. Its code hands off with `ctx.context.run.handoff` (main model) or `ctx.harness.handoff` (root agent), as in [Hand off from code](#2-hand-off-from-code).

## 2. Hand off from code

An agent can decide in code. In a root agent that answers a turn, call `ctx.harness.handoff`:

```ts group=harness-handoffs
export const triage = defineAgent({
  name: 'triage',
  description: 'Sorts new requests',
  run: async (ctx) => {
    if (!ctx.harness) throw new Error('This agent must run in a harness.')
    await ctx.harness.handoff({ to: 'billing', note: 'Refund for order 42' })
    return 'I pass you to billing.'
  },
})
```

A tool of the main model uses `ctx.context.run.handoff`. Type the tool with `HarnessRunContext`:

```ts group=harness-handoffs
import { toolDefinition } from '@tanstack/ai'
import { z } from 'zod'
import type { HarnessRunContext } from '@tanstack/ai-harness'

export const escalate = toolDefinition({
  name: 'escalate',
  description: 'Send the user to billing',
  inputSchema: z.object({ orderId: z.string() }),
}).server<HarnessRunContext>(async ({ orderId }, ctx) => {
  await ctx.context.run.handoff({ to: 'billing', note: `Refund for order ${orderId}` })
  return 'Billing answers next.'
})
```

- The part that handed off ends. Then the target answers, in the same turn.
- Outside a turn of a harness with `routing`, both calls reject.
- A target that is not a root agent rejects, and the agent that called it keeps the turn.

The router can hand off too. Return `{ handoff: 'billing', note }` from `routing.router`. See [Route a turn to an agent](./subagents#route-a-turn-to-an-agent).

## What the target gets

- Its own system prompts and tools. The tools of the agent that handed off do not go with it.
- The saved transcript of the thread. `routing.history` sets how it sees the turns of the other speakers. See [Choose what later turns see](./subagents#choose-what-later-turns-see).
- The note, in the transcript, in the log, and in the `harness.handoff` event.
- The provider keys of the user who sent the turn.

The `handoff` tool call of the main model is in the transcript already. A root agent keeps its own tool calls in its own transcript. So a handoff from a root agent, from the router, or from code adds the same two messages before the target answers:

- An assistant message with a `handoff` tool call. Its arguments are `{ to, note }`.
- The tool result, for example `Handed off to billing. billing answers next.`

Both messages have `metadata.harness.handoff.by` (`'tool'`, `'router'`, or `'code'`). When an agent handed off, they also have its name in `metadata.harness.agent`.

What the model of the target gets depends on `routing.history`:

- `'own'` (default): the turns of the other speakers are labeled text in a user message, for example `main:\n...`. The handoff is one text line, for example `main handed off to billing. Note: Refund for order 42`. When billing hands back, the main model gets `billing handed off to main.` the same way.
- `'text'`: the messages of the main model stay as they are, and the two handoff messages come after them. So the prompt cache of the provider still holds.
- `'all'`: each routed host message becomes the child transcripts of that run, with their tool calls.

With `routing.giveModelsHandoffTool: false`, the models have no `handoff` tool. Then the harness adds one assistant message with the same text and the note.

The `agents()` plugin has its own primary agent, its `agent` config and `/agent`. That one changes the prompt and the tools of the main model. A handoff does not change it, and it does not change the active agent. See [Switch between agent profiles](./agents).

## 3. Show who answers

Each message that an agent writes has its name in `metadata.harness.agent`. In the [session view](./custom-ui), an assistant message has `agent`. It is `undefined` for the main model:

```tsx ignore
import { useSelector } from '@tanstack/react-store'
import { createHarnessClient } from '@tanstack/ai-harness/client'
import { createSessionView } from '@tanstack/ai-harness/view'

const view = createSessionView(
  createHarnessClient({ url: '/api/harness', threadId: 'user-1-thread' }),
)

export function Messages() {
  const messages = useSelector(view.store, (state) => state.messages)
  return messages.map((message) =>
    message.role === 'assistant' ? (
      <p key={message.id}>
        <strong>{message.agent ?? 'Support'}: </strong>
        {message.parts.map((part) => (part.type === 'text' ? part.text : '')).join('')}
      </p>
    ) : null,
  )
}
```

Each handoff also streams a `CUSTOM` event named `harness.handoff` (`HARNESS_EVENTS.handoff`). Its value has these fields:

- `from` and `to`: an agent name, `null` for the main model, or `{ human: true }` for a person.
- `note`: the note, when there is one.
- `by`: `'tool'`, `'code'`, `'router'`, or `'operator'`.
- `runId`: the turn. A handoff to a person also has `waitId`.

## 4. Hand off to a person

Some users need a person. Set `routing.allowHandoffToHuman: true`. Then the `handoff` tool also takes `{ human: true }`:

```ts group=harness-handoffs
import { membersOnly } from '@tanstack/ai-harness'
import { createHarnessHandler } from '@tanstack/ai-harness/server'

export const desk = defineHarness({
  name: 'acme/desk',
  adapter: openaiText('gpt-6.1-sol'),
  systemPrompts: ['If the user asks for a person, hand off to { human: true }.'],
  agents: [billing],
  routing: { router: () => undefined, allowHandoffToHuman: true },
})

// Your own login check: a session token to a user.
const users = new Map([
  ['Bearer token-ada', { id: 'ada', tenantId: 'acme' }],
  ['Bearer token-olga', { id: 'olga', tenantId: 'acme' }],
])

export const deskHost = createHarnessHost({
  persistence: memoryPersistence(),
  access: {
    getUser: ({ request }) => users.get(request.headers.get('authorization') ?? '') ?? null,
    rules: membersOnly(),
  },
})

export const handler = createHarnessHandler({ host: deskHost, harness: desk })
```

When an agent hands off to a person:

- The handoff opens a `human` wait. The note is its `message`. The wait does not expire.
- The turn ends `interrupted`, and the session pauses.
- A user message during the pause goes into the transcript. No model answers it.

`ctx.harness.handoff({ to: { human: true } })` and `run.handoff` work the same way. Without `routing.allowHandoffToHuman`, a handoff to a person rejects.

### Reply as the operator

A person from your team replies with `as: 'operator'`:

1. Share the thread with the operator, with the role `operator`. Ada owns the thread here. See [Share a thread between people](./shared-threads#2-share-the-thread).
2. Send the reply as the operator.

```ts group=harness-handoffs
const ada = { id: 'ada', tenantId: 'acme' }
const olga = { id: 'olga', tenantId: 'acme' }

export async function addOperator(threadId: string) {
  await deskHost.sessions.share({ threadId, userId: 'olga', role: 'operator', user: ada })
}

export async function reply(threadId: string, text: string) {
  const session = await deskHost.open(desk, { threadId, user: olga })
  await session.send(text, { as: 'operator' })
}
```

- The reply goes into the transcript as an assistant message, with `metadata.harness.operator` set to the id of the operator. No model runs.
- The sender needs the `operator` access action. With `membersOnly()`, only the role `operator` has it. The owner and members do not, so the user who waits cannot act as the person. To change this, pass `membersOnly({ operator: { roles: ['owner', 'operator'] } })`.
- Files in the reply go into a user message after it, because a model takes files only from a user. `metadata.harness.operatorAttachment` marks it, and a view shows the files with the reply.
- Without an open `human` wait, the receipt is `rejected` with `no_human_wait`.

In the browser, the operator uses the same option: `client.send(text, { as: 'operator' })`, or `view.send(text, { as: 'operator' })` in a [session view](./custom-ui). The reply shows in each open view at once.

### End the pause

The operator ends the pause with an answer to the `human` wait:

```ts group=harness-handoffs-client
import { createHarnessClient } from '@tanstack/ai-harness/client'
import type { desk } from './harness'

const client = createHarnessClient<typeof desk>({
  url: '/api/desk',
  threadId: 'case-42',
  headers: { authorization: 'Bearer token-olga' },
})

const snapshot = await client.snapshot()
const wait = snapshot.pendingWaits.find((open) => open.kind === 'human')
if (wait) {
  await client.answer({ questionId: wait.waitId, value: { handBack: 'billing' } })
}
```

- `{ resume: true }` gives the thread back to the agent that answered before the handoff.
- `{ handBack: 'billing' }` gives it to that agent. `{ handBack: 'main' }` gives it to the main model.
- Any other value is `rejected` with `invalid_answer`. An unknown agent is `rejected` with `unknown_agent`.
- The wait can also end with `session.resolve` or a cancel. Then the agent that answered before the handoff gets the thread back. Each of these needs the `operator` action.
- The answer starts no turn. The held user messages wait for the next message, or for `session.continueWithoutMessage()`.

## 5. Move a conversation to another harness

The case must leave the support harness. The billing team runs its own harness, with its own tools and plugins. `host.transfer` makes a new thread under the target harness and copies only the envelope:

```ts group=harness-handoffs
export const billingDesk = defineHarness({
  name: 'acme/billing',
  adapter: openaiText('gpt-6.1-sol'),
})

export const billingHandler = createHarnessHandler({ host: deskHost, harness: billingDesk })

// Mount on POST /api/move-to-billing?threadId=...
export async function moveToBilling(request: Request) {
  const user = await deskHost.getUserOfRequest({ request })
  if (!user) return new Response('Unauthorized', { status: 401 })
  const threadId = new URL(request.url).searchParams.get('threadId')
  if (!threadId) return new Response('Missing threadId', { status: 400 })
  const result = await deskHost.transfer({
    from: { harness: desk, threadId },
    to: { harness: billingDesk },
    envelope: { note: 'Refund for order 42. The user waits.', messages: 'summary' },
    user,
    transferId: `refund-${threadId}`,
  })
  return new Response(result.threadId)
}
```

`envelope.note` is the first message of the target. `envelope.messages` picks what comes after it:

- `'none'` (default): no message.
- `'summary'`: one summary message. The model of the source harness writes it, with the keys of the user. The summary call stops after 2 minutes, and then the transfer fails. Its usage counts in the source thread under the source `transfer`. See [Usage of the router and transfers](./usage#usage-of-the-router-and-transfers).
- `'all'`: the settled transcript, with new message ids and a copy of each media file.

Only settled messages move. A tool call with no result yet stays behind. Plugin state, shared state, credentials, waits, settings, and plugin config never move. The source thread keeps running.

The browser then opens the target thread on the handler of the target harness:

```ts group=harness-handoffs-client
import type { billingDesk } from './harness'

const response = await fetch('/api/move-to-billing?threadId=case-42', {
  method: 'POST',
  headers: { authorization: 'Bearer token-ada' },
})
const threadId = await response.text()

const billingClient = createHarnessClient<typeof billingDesk>({
  url: '/api/billing',
  threadId,
  headers: { authorization: 'Bearer token-ada' },
})
await billingClient.send('Hi, I am still here.')
```

### Rules of a transfer

- Both threads are in the tenant of `user`. A transfer to another tenant cannot be named.
- With access, the user needs `transfer` on the source. With `membersOnly()`, only the owner has it. A target that exists needs `send` too.
- A new target has the user as its only member, the owner. A thread that exists must belong to `to.harness`.
- A retry with the same `transferId` makes no second thread and copies nothing again.
- If another host owns the target log, the transfer throws `LogOwnedElsewhereError`.

How the two threads stay linked:

- Both logs get a `harness.transferred` record with the same `transferId`. See [Read the log](./session-log#read-the-log).
- The index entry of the target has `metadata['harness:transferredFrom']`. The source has `metadata['harness:transferredTo']`. The host writes these keys itself, and your `metadataSchema` does not check them.
- `host.events()` yields a `transferred` event. Copy your own access rows for the target there.

A [fork](./fork-and-reset) stays in its harness. `host.fork` with a thread of another harness throws, so use `host.transfer` for that move.

## What you have now

- Agents that hand the conversation to each other, from a tool, from code, or from the router. The tool can be your own, with the fields that you need.
- A log that keeps who answers, also after a restart.
- A UI that shows the name of the agent on each message.
- A pause for a person, operator replies, and a way to give the thread back.
- A conversation that moves to another harness with only the envelope that you name.
