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

# Agent Handover

> Let one agent pass its work to another agent when a Run completes, for triage, escalation, and multi-step workflows.

Agent Handover lets one step pass its work to another when a Run completes. Use it to build multi-step workflows where a general agent routes work to a specialist, or where one stage of a process hands off to the next.

## Three ways to hand over

Pick one per step—a step uses exactly one of these, never a mixture.

| | **Handover to** field | **@-mention in the AOP** | **Handover options** |
| - | - | - | - |
| **What happens** | Always runs the next step when this one finishes | The agent decides at runtime whether to hand over, and to which target | The code decides at runtime, from the set you declared |
| **How many targets** | Exactly one | As many as you mention | As many as you declare |
| **Available on** | Agents and code steps | Agents only | Code steps only |
| **Can target** | An agent or a code step | Agents only | An agent or a code step |
| **Use it when** | The next step should always run | The right next step depends on what the agent finds | The right next step is a calculation, not a judgement |

Setting one turns the others off: if your instructions @-mention a handover, the **Handover to** field is disabled; once **Handover to** is set you cannot add @-mentions; and a code step in options mode has no single next step. This is deliberate—if a step had two, something could decide whether a step you meant to always run actually runs.

## Key Capabilities

* **Route work automatically**: A step can hand off with no manual intervention.
* **Always-on, agent's choice, or the code's**: Use the **Handover to** field for a fixed next step, @-mentions to let the agent route, or handover options to let a code step branch.
* **Reach code steps**: The **Handover to** field can target a code step—useful when an agent classifies and a code step then transforms the result deterministically.
* **Works with Queue**: For case-based workflows, the case is released and routed to the target through the regular case dispatcher.
* **Works with standalone Runs**: For non-case Runs, a new Run is started for the target, not carrying over any context from the source run.

## How to Use It

### Set a fixed next step

<Steps>
  <Step title="Open the step" icon="square-pen">
    Open the agent or code step you want to hand over from, and expand its setup section.
  </Step>

  <Step title="Pick the next step" icon="arrow-right">
    Next to **Handover to**, choose the agent or code step that should run next. There is only one slot—this is the step that always runs when this one finishes cleanly.

    If the field is disabled, your instructions already @-mention a handover. Remove those mentions first.
  </Step>

  <Step title="Check the Flow tab" icon="share-nodes">
    Open the automation's **Flow** tab. The new edge appears between the two steps, labelled **Then runs**—distinct from the **Handover** label used for @-mention handovers, which the agent may or may not take.
  </Step>
</Steps>

### Let the agent choose

<Steps>
  <Step title="Open the Agent Builder" icon="square-pen">
    Open the agent you want to configure as a handover source and navigate to the AOP editor.
  </Step>

  <Step title="Mention a target agent" icon="at-sign">
    In the AOP textarea, type `@` followed by the name of the agent you want to hand off to. A dropdown appears listing available agents in your team.

    Select the agent. A badge is inserted inline in the AOP text—this registers it as an allowed handover target.

    Place the mention within naturally written rules for handover. You can add multiple targets if your agent may route to different specialists depending on the situation.

    **Example AOP instruction:**

    > After reviewing the customer request, determine whether it needs billing support or technical support. If billing, hand over to @Billing Specialist. If technical, hand over to @Technical Support.
  </Step>

  <Step title="Save and test" icon="save">
    Save the AOP. On the next Run, the agent will have access to a `request_handover` tool. At runtime, the agent decides when to use it based on your AOP instructions.
  </Step>
</Steps>

### Let the code decide

A code step can branch. Instead of one fixed next step, you declare the set of steps its program may hand over to, and the program picks one when it runs. Use this when the decision is a comparison rather than a judgement—an amount over a threshold, a validation that failed, a record that already exists. Routing that in code is faster, cheaper and more reliable than inserting an agent to re-derive a fact the code already had.

<Steps>
  <Step title="Open the code step's Handover to row" icon="square-pen">
    Open the code step and find the **Handover to** row, then choose **Let the code decide**.
  </Step>

  <Step title="Pick the steps the code may reach" icon="list-checks">
    Select every step the program may hand over to. They must be in the same automation. Each selected option shows its id with a copy button—your program addresses targets by id, so copy the ones you need into your code.

    Choose whether the handover is **required**. When it is, a Run that finishes without requesting one fails, which is how you catch a program that fell through a branch it should have routed. Leave it optional when the step is genuinely the last one on some paths.
  </Step>

  <Step title="Request one at run time" icon="code">
    Read the set and pick from it:

    ```python theme={"dark"}
    duvo.handover_options
    # -> [{"id": "3f2a…", "name": "Approve & Pay"}, {"id": "8c11…", "name": "Send to Review"}]

    if total > THRESHOLD:
        duvo.request_handover(target_agent_id=APPROVAL_STEP_ID)
    else:
        duvo.complete_case(case_id=case["id"], reason="Under threshold")
    ```
  </Step>
</Steps>

<Warning>
  **Do not settle the case on a Run that hands over.** `complete_case`, `fail_case` and `postpone_case` move the case out of claimed status, and the target step then never receives it. On a Run that hands over, the handover is the outcome.
</Warning>

A few more rules worth knowing:

* The handover is **recorded, then dispatched** after your program exits cleanly. Keep working normally after the call—and note that a crash or a non-zero exit cancels the handover along with the Run.
* A Run hands over **at most once**. Calling with the same id twice does nothing; calling with a different one raises, because that is a bug rather than a change of mind.
* An id outside the declared set raises straight away, without a round trip, naming what the step *can* reach.

### Handover flow

This is the @-mention flow. A **Handover to** successor is simpler: when the Run completes cleanly, the next step always runs. Handover options sit in between: the program chooses, and the platform dispatches the choice after the Run completes.

```mermaid theme={"dark"}
flowchart TD
    A[Agent reviews work during Run] --> B{Handover needed?}
    B -->|No| C[Agent completes the Run normally]
    B -->|Yes| D[Agent calls request_handover to a target named in the AOP]
    D --> E{Workflow type}
    E -->|Case-based| F[Case released and routed to target agent via case dispatcher]
    E -->|Standalone Run| G[New Run started for target agent, no source context carried over]
    F --> H[Target agent picks up and continues processing]
    G --> H
    H --> I[Source Run shows handover target in its results]
```

### Viewing handover results

After a handover occurs, the source Run shows the handover target in its results. For case-based workflows, the case timeline reflects which agent handled each stage.

## When to Use It

* **Triage workflows**: A general agent reviews incoming cases and routes each one to the right specialist.
* **Escalation paths**: An agent handles routine cases and escalates complex ones to a more specialized agent.
* **Sequential pipelines**: One agent completes an initial stage (data gathering, analysis) and hands off to another for the next stage (reporting, action).
* **Domain specialization**: Route work to an agent that has the right connections and context for a specific task type.
* **Deterministic follow-up** (**Handover to**): An agent interprets a request, and a code step then applies the result exactly the same way every time.
* **Escalate to a person, then act** (**Handover to**): A code step flags a case it will not decide, an agent conducts the conversation with the approver, and a further code step acts on the recorded decision.

## Things to Know

* A step uses exactly one of the three: the **Handover to** field, AOP @-mentions, or handover options. Switching a code step between a single next step and options clears the one it is leaving, and the builder says so before you save.
* **Handover to** takes effect when you publish the revision that sets it, like any other setup change.
* An agent can only hand off to agents configured as targets in its AOP—it cannot hand off to arbitrary agents at runtime.
* If the step named in **Handover to** is deleted or moved to another team, the Run records that the next step could not be reached rather than quietly finishing the chain.
* If a mentioned agent is deleted, the mention badge turns red in the AOP editor. Remove the deleted target before the next run.
* For case-based handovers, the target agent must have the **Queue (Consumer)** connection enabled. Agents without it are not available as handover targets in queue workflows.
* A code step's handover options are frozen when the Run starts, so editing the step mid-Run cannot widen what a running program may reach.
* Installing a module template or cloning an automation remaps the option **wiring** for you, but not any ids written into program text. If you copied an id into your code, update it in the copy—the first branching Run refuses an id it cannot reach rather than routing somewhere unexpected.


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