Handoffs

Handoffs

The handoff protocol — how agents pass tasks to each other.

HandoffRequest

When an agent wants to delegate to another agent:

interface HandoffRequest {
  to: string;                // Target agent name
  task: string;              // Task to hand off
  context?: string;          // Additional context
  artifacts?: unknown;       // Data to pass
  confidence?: number;       // How confident the handoff is appropriate (0-1)
  timeout?: number;          // Handoff timeout (ms)
}

HandoffResult

The result returned from the target agent:

interface HandoffResult {
  status: 'completed' | 'failed' | 'rejected' | 'timeout';
  output: string;
  runId: string;
  agentName: string;
  trace?: unknown;
}

HandoffRecord

The Coordinator records every handoff:

interface HandoffRecord {
  from: string;
  to: string;
  task: string;
  status: 'completed' | 'failed' | 'rejected' | 'timeout';
  runId: string;
  duration: number;
  confidence?: number;
  rejected?: boolean;
  rejectionReason?: string;
  fallbackUsed?: boolean;
}

Handoff Rejection

Handoffs can be rejected based on trust rules:

const coordinator = new Coordinator({
  agents: { a, b, c },
  trustModel: {
    requireExplicitRoutes: true,
    allowedHandoffs: {
      a: ['b'],  // A can only hand off to B
    },
  },
});

// If A tries to hand off to C → rejected

Fallback Agents

Configure a fallback agent for rejected handoffs:

trustModel: {
  fallbackAgent: 'general-agent',
},

Next Steps

Trust — trust model configuration
Workspace — shared state between agents