> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfer to agent step

> Hand a call to another agent in your project with a Transfer to agent step, and choose whether it receives the conversation so far and your variables.

A Transfer to agent step hands the call to another agent in the same project, on the same call. There's no new phone call: the caller stays on the line and the other agent takes over, with its own voice, prompt and settings. You choose whether it gets the conversation so far and your variables.

## When to use it

* To split a large agent into specialists, such as a reception agent that hands over to a billing agent or a sales agent.
* To switch to an agent built for another language or dialect.
* To reuse an agent you already have instead of rebuilding its steps in this flow.

To hand the caller to a person or a phone line, use [Transfer call](https://docs.tryhamsa.com/agents/flow/steps/transfer-call.md).

## Before you start

The project needs at least one other agent. If there's none, the panel shows "No agents available. Please create an agent first before using transfer to agent." or "You only have this agent in your account. Add another agent to use Transfer to Agent." See [Create, import and manage agents](https://docs.tryhamsa.com/agents/build/create-an-agent.md).

## Add a Transfer to agent step

**1. Add the step**

On the canvas, click **Add node** and choose **Transfer to agent** ("Transfer conversation to another agent"). The panel title reads **Transfer agent**.

**2. Pick the agent**

Under **Transfer configuration**, open **Transfer to agent** and choose an agent. The list shows the other agents in this project, flow or single prompt.

**3. Choose what to hand over**

Open **Handoff options** and turn on **Handoff conversation**, **Handoff variables**, or both.

**4. Connect On Failure**

Connect **On Failure** to a step that tells the caller and offers another way forward.

## Fields

| Field | What it does | Default |
| - | - | - |
| **Transfer to agent** | The agent that takes over. Required: "Please select an agent to transfer to". | None ("Select an agent") |
| **Handoff conversation** | "Pass the conversation history to the receiving agent". The new agent sees what was said so far and is told not to greet the caller again or ask for what they already gave. | Off |
| **Handoff variables** | "Pass current variables to the receiving agent". The new agent can use every variable collected or set so far. | Off |
| **Transfer message** | What this agent says before handing over. **Static** says the text as written; **Prompt** lets the agent phrase it from your instruction. It can use variables. Leave it empty to hand over without a word. | Empty, Static |

![A Transfer to agent step handing over to Billing Assistant, with its Handoff options open and Handoff conversation and Handoff variables on](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/flow/steps/transfer-agent-step-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=143cce250922f921c94627f7d290a67e)

With both off, the receiving agent starts fresh: it doesn't know what was said and has none of your flow's variables.

Use **Transfer message** to tell the caller they're being passed on, for example "I'm connecting you with our billing team now." The receiving agent then takes over on the same call.

## Transitions

| Transition | Taken when |
| - | - |
| **On Failure** | The transfer couldn't start, for example because no agent is selected. |

**On Failure** is created with the step and can't be removed. There's no success path: once the other agent takes over, this flow ends.

You can also add **Skip if** to this step: when its conditions already hold as the call arrives, the call goes straight to its target and the step doesn't run. See [Skip if](https://docs.tryhamsa.com/agents/flow/transitions.md#skip-if).

## How it works on a call

1. The step's local variables are set.
2. The receiving agent is loaded and takes over the call, with its own voice, prompt and settings.
3. With **Handoff conversation** on, it gets the conversation so far as context. With **Handoff variables** on, it shares this call's variables.
4. If the transfer can't start, the call takes **On Failure** and this agent carries on.

If the receiving agent can't be loaded at the moment of the switch, the call ends.

## Good to know

* Steps built through the API without the two handoff fields hand over both the conversation and the variables. Steps built in the app always save them, off unless you turn them on.
* **Confirm before proceeding**, in the **Global** section, makes the agent check with the caller before handing over.

## Related

> [card] [Transfer call step](https://docs.tryhamsa.com/agents/flow/steps/transfer-call.md)
>
> Hand the caller to a person or a phone line.

> [card] [Variables](https://docs.tryhamsa.com/agents/variables/overview.md)
>
> What gets handed over with Handoff variables.

> [card] [Create, import and manage agents](https://docs.tryhamsa.com/agents/build/create-an-agent.md)
>
> Build the agent you hand over to.

> [card] [Global steps](https://docs.tryhamsa.com/agents/flow/global-steps.md)
>
> Make a handoff reachable from anywhere in the flow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.