Structured Handoff Design

A handoff is the moment when responsibility for a work item transfers from one agent to another. This is the most failure-prone point in any multi-agent workflow. Information gets lost. Context gets distorted. Assumptions get made. The structured handoff protocol prevents these failures by requiring every handoff to include four components: the work product, the completion status, the context summary, and the next action.

The work product is what the sending agent produced — the research findings, the draft, the analysis. The completion status declares whether the work is complete, partial, or blocked: "Research complete. All five competitors profiled. No data found for Company E pricing — marked as incomplete." The context summary captures decisions made during execution that the receiving agent needs to know: "Used 2025 annual report for revenue figures because Q4 2025 was not published yet." The next action states what the receiving agent should do with the handoff: "Draft a competitive analysis using these five profiles. Flag Company E pricing gap in the analysis."

interface Handoff {
  from: string;
  to: string;
  traceId: string;
  workProduct: unknown;       // The actual deliverable
  status: 'complete' | 'partial' | 'blocked';
  gaps: string[];             // What is missing or incomplete
  contextNotes: string[];     // Decisions made during execution
  nextAction: string;         // What the recipient should do
}

// HUNTER → CLOSER handoff
const leadHandoff: Handoff = {
  from: 'HUNTER',
  to: 'CLOSER',
  traceId: 'lead-2026-0222-047',
  workProduct: { /* lead profile data */ },
  status: 'complete',
  gaps: [],
  contextNotes: [
    'Decision maker confirmed via LinkedIn — VP of Engineering',
    'Budget authority verified through org chart, not direct confirmation',
  ],
  nextAction: 'Schedule discovery call. Lead expressed urgency — 48hr window.',
};