Agent Handover

​

Three ways to hand over

​

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

​

Let the agent choose

​

Let the code decide

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")

• 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

​

Viewing handover results

​

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.