Monorch

Multi-agent handoff

Declare handoff targets on an agent. The model gets handoff_to_<name> tools, or you force a transfer with handoff().

Pattern

handoff.ts
import { agent, mock } from "@monorch/ai";

const billing = agent({
  name: "billing",
  model: mock([{ text: "Refund initiated." }]),
  instructions: "Handle billing.",
});

const triage = agent({
  name: "triage",
  model: mock([
    {
      toolCalls: [
        {
          id: "h1",
          name: "handoff_to_billing",
          arguments: { message: "Customer wants a refund" },
        },
      ],
    },
  ]),
  instructions: "Route billing issues to billing.",
  handoffs: [billing],
});

const result = await triage.run("I need a refund");
// events include handoff; billing run continues; run_end status handed_off then completed

// or force:
await triage.handoff(billing, "Customer wants a refund");

Notes

Target must be listed in handoffs. Unique agent names matter; getAgent resolves by name. Denied targets throw HANDOFF_DENIED — error codes.

FAQ