Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Handoff

Pattern

A reusable solution you can apply to your work.

When work moves between agents or sessions, a handoff curates the context the receiver needs so nothing important is lost and nothing irrelevant comes along.

Also known as: Context Transfer, Agent Relay

Understand This First

  • Agent – handoffs happen between agents or agent sessions.
  • Externalized State – the handoff artifact is externalized state that both sides can inspect.
  • Context Window – handoffs exist because context windows don’t travel between sessions.

Context

As agent workflows grow longer and more complex, they hit a practical ceiling: a single agent session can’t hold everything. The context window fills up, the task branches into subtasks that belong in separate threads, or a different agent with different tools needs to pick up where the first left off. At each of these boundaries, work has to move from one context to another.

That transfer point is where things go wrong. The naive approach is to dump the full conversation history into the next session. This fails in two ways. The receiving agent wastes tokens parsing irrelevant exchanges, and worse, old internal reasoning from the sending agent can actively confuse the receiver. A debugging dead-end that the first agent explored and abandoned looks, to the second agent, like a line of investigation still worth pursuing.

Handoff is the pattern that governs this boundary. Instead of dumping everything or starting blind, you curate a transfer artifact: a structured document that carries forward what the next agent actually needs and leaves behind what it doesn’t.

Problem

How do you transfer work between agents or sessions without losing critical context or polluting the receiver with noise?

The problem shows up in three common situations: when a long-running task exceeds a single context window, when a subagent finishes and reports back to its parent, and when agent teams divide work across specialized roles. In each case, the sending side has accumulated context (decisions, constraints, partial results, remaining work) that the receiving side needs. But the receiving side has a fresh context window and a different focus. The wrong transfer strategy wastes that clean slate.

Forces

  • Context is perishable. Decisions, constraints, and rationale accumulate during a session but vanish when the session ends unless someone captures them.
  • More context isn’t better context. Dumping a full conversation into the next session wastes tokens and confuses the receiver with irrelevant reasoning.
  • Authority must transfer cleanly. The receiving agent needs to know what it’s allowed to do, not just what it should know.
  • Handoffs are invisible failures. When a handoff loses something important, the downstream agent doesn’t know what it’s missing. The error surfaces later as a wrong decision.

Solution

When work moves between agents or sessions, construct a handoff artifact: a structured summary that captures what the receiver needs and omits what it doesn’t. A good handoff artifact includes five elements:

Objective. What the receiving agent is supposed to accomplish. State this directly, not as a reference to earlier conversation.

Constraints. Rules the receiver must follow: coding conventions, architectural decisions already made, files it shouldn’t touch, permissions it has.

Prior decisions. What was tried, what worked, what was rejected and why. This is the highest-value part of a handoff. Without it, the receiver repeats work the sender already did.

Current state. What files have been modified, what tests are passing, what the code looks like right now. Point to concrete artifacts whenever possible.

Next steps. What remains to be done, in what order, and any known risks or open questions.

The key discipline is curation. A handoff isn’t a summary of the conversation. It’s a briefing for the next agent, written from the receiver’s perspective. Ask: what would I need to know if I were picking this up cold?

Some harnesses support handoffs as a first-class feature. OpenAI’s Agents SDK provides input_filter and handoff_history_mapper parameters that let you control exactly what history the receiving agent sees. Amp replaced its earlier compaction feature with a dedicated Handoff tool that carries context forward without dragging the full past along. LangGraph documents handoffs as a named orchestration pattern and warns against including “full subagent conversation history” in transfers.

When your harness doesn’t have built-in support, you can implement handoffs manually. Write the handoff artifact to a file (a markdown document, a JSON object, a structured prompt section) and pass it as the opening context for the next session. The Ralph Wiggum Loop is one common implementation: a shell loop that restarts agents with a fresh context and a plan file that serves as the handoff artifact between iterations.

Tip

Write the handoff artifact before you close the sending session, not after. The sending agent has the context to write a good briefing. Once the session is gone, you’re reconstructing from memory.

How It Plays Out

A developer is building a feature that touches the API layer, the database schema, and the frontend. She starts an agent session to design the API. After forty minutes, the design is solid but the context window is getting crowded with exploration and dead ends. Rather than pushing forward into the database work in a degraded context, she asks the agent to write a handoff document: the API design decisions, the schema constraints those decisions imply, the endpoint signatures, and three open questions about caching. She opens a fresh session, pastes the handoff document as the opening prompt, and the new agent picks up the database work with a clean context and a clear brief.

In a multi-agent system, a research subagent finishes scanning a codebase for uses of a deprecated API. It produces a structured report: 47 call sites across 12 modules, grouped by module, with notes on which ones have test coverage and which don’t. The parent agent receives this report as a handoff artifact. It doesn’t receive the subagent’s internal search queries, false starts, or the 200 files it opened and discarded. The parent’s context stays clean for the planning work that comes next.

Warning

The most common handoff failure is including too much. When the sending agent dumps its full reasoning chain into the transfer, the receiving agent treats that reasoning as current context rather than history. Old hypotheses get pursued, rejected approaches get revisited, and the receiver’s fresh perspective (one of the main reasons you created a new session) is compromised by the sender’s stale thinking.

Consequences

Good handoffs make long-running and multi-agent workflows practical. Each agent or session operates with a clean context, focused on its specific task, while preserving the continuity of the overall work. The handoff artifact also creates an audit trail: you can read the sequence of handoff documents to understand how a piece of work progressed across sessions.

The cost is the effort of writing the handoff. Someone (the sending agent, the parent agent, or the human) has to pause, reflect on what matters, and write it down. This takes time and tokens. Poorly written handoffs lose critical details. Over-specified handoffs constrain the receiver unnecessarily.

There’s also a design question: how structured should the handoff be? A free-text summary is flexible but easy to get wrong. A rigid schema (JSON with required fields) is harder to lose information from but may not capture everything that matters. In practice, teams converge on semi-structured formats: a markdown template with required sections but free-text content within each section.

  • Depends on: Agent – handoffs happen between agents or agent sessions.
  • Depends on: Externalized State – the handoff artifact is externalized state.
  • Contrasts with: Compaction – compaction compresses context within a session; handoff curates context between sessions.
  • Uses: Thread-per-Task – each side of a handoff typically runs in its own thread.
  • Enables: Agent Teams – teams coordinate through handoffs.
  • Related: Subagent – subagent results returned to a parent are a form of handoff.
  • Related: Context Rot – handoff is a defense against context rot in long-running work.
  • Related: Delegation Chain – each link in a delegation chain involves a handoff.
  • Related: Research, Plan, Implement – phase transitions in RPI are handoffs between fresh contexts.

Sources

  • OpenAI’s Agents SDK (2025-2026) formalized handoff as the core abstraction for multi-agent coordination, providing configurable history filtering (input_filter, handoff_history_mapper) to control what context the receiving agent sees.
  • LangChain’s LangGraph documentation identifies handoffs as a first-class orchestration pattern, with specific guidance on filtering conversation history during agent transfers.
  • Anthropic’s design guidance for long-running agent workflows describes “context reset” as a core strategy: clearing the context window entirely and starting a fresh agent with a structured briefing rather than compacting within a single session.
  • Adaline Labs’ multi-agent framework (2026) identifies handoffs as one of four control-plane primitives (alongside permissions, visibility, and recovery), calling them “critical moments where context, authority, and verification converge.”