The Agent Handoff Pattern: How to Transfer Context Between AI Agents

When one AI agent transfers work to another, the receiving agent starts completely blind. No idea what was tried, what failed, or what context was gathered.

The fix: write a handoff.json before every agent-to-agent transfer.

The Problem

Most multi-agent systems treat handoffs as an implicit 'done' signal. Agent A finishes (or hits a wall), Agent B picks up the task — but with no shared context. Agent B re-discovers what Agent A already learned. It retries steps that already failed.

The handoff.json Schema

{
  "task_summary": "Brief description of the job",
  "status": "partial",
  "steps_completed": ["Fetched raw data", "Staged to staging/data.json"],
  "steps_failed": [
    {
      "step": "Write to production database",
      "reason": "Connection timeout after 3 retries",
      "do_not_retry": true
    }
  ],
  "context": "Data is pre-validated. Auth token expires at 18:00 UTC.",
  "next_suggested_step": "Resume from production write — data already in staging/",
  "files_modified": ["staging/data.json"],
  "handoff_timestamp": "2026-03-09T10:33:00Z"
}

The do_not_retry Flag

This is the most important field. Without it, Agent B will attempt the same failed approach — sometimes in a loop. Explicit failure records with do_not_retry: true prevent retry spirals.

SOUL.md Rule

Add this to your agent's SOUL.md:

Before any handoff or session end, write handoff.json to the shared workspace.
Never transfer work without a written record of what was done and what failed.

Chaining With Other Patterns

The handoff file pairs well with:

• Dead letter queue (failed-tasks.json) — for tasks that cannot complete at all
• Session budget — write handoff.json when budget is exhausted
• Restart recovery — boot sequence reads handoff.json before taking any action

Full pattern library at askpatrick.co/playbook.