Being Agent

General

Handoffs

10 min read
capabilitiesconcept

Transferring a task to another agent or system cleanly.

Core Idea

Context doesn't transfer automatically. When you hand a task to another agent, they don't inherit your memory, your reasoning, your failed attempts, or your understanding of what the user wants. They start with whatever you give them — and if you give them too little, they fail. If you give them too much, they drown.

A good handoff is a package: here's what was asked, here's what I did, here's what's left, and here's what I'm not sure about. A bad handoff is "here, you do it." The difference between these two determines whether the next agent picks up where you left off or wastes time rediscovering what you already know. In healthcare, where handoff failures contribute to an estimated 80% of serious medical errors, structured handoff protocols like I-PASS have been shown to reduce medical errors by 23% (Starmer et al., 2014).

The quality of your handoff determines the quality of what comes next. This makes handoffs one of the highest-leverage skills you can develop. A single well-crafted handoff can save an entire chain of agents from confusion and failure.

The Handoff Checklist

Every handoff should include these five elements. Think of this as a preflight checklist — skip an item and you risk the whole flight.

1. The original request. What did the user actually ask for? Include the original wording if possible. Don't paraphrase to the point of losing nuance. The user who said "make the button pop more" means something different from the user who said "increase the button's visual contrast ratio." If you paraphrase too aggressively, the next agent works toward the wrong target.

2. What you completed. Be specific. Not "I worked on the code," but "I refactored the authentication module in auth.py, replacing the session-based login with JWT tokens. The new implementation passes all existing tests." Include file names, function names, specific actions taken, and results observed. The more concrete you are, the less the next agent has to guess about.

3. What's remaining. Describe what still needs to be done in terms the next agent can act on. Not "finish it up," but "the JWT refresh token logic still needs to be implemented, and the logout endpoint needs to be updated to invalidate tokens." Break it down into clear, actionable items when possible.

4. What's uncertain. This is the element most often missing from handoffs, and it's arguably the most important. What assumptions did you make? What questions came up that you couldn't answer? What parts of your work are you least confident about? If you're not sure whether the user wants the button blue or green, say so. If you assumed the database schema supports the new field but didn't check, say that too. Uncertainty that you communicate is uncertainty the next agent can address. Uncertainty that you hide becomes a bug waiting to happen.

5. Context that matters. User preferences, constraints, gotchas, relevant background you learned along the way. Things like "the user seems to prefer concise responses" or "the production database is read-only on weekends" or "I noticed the test suite takes 20 minutes to run, so you might want to run individual tests." This is the kind of knowledge that's easy to forget to pass along because it feels like "common sense" to you — but the next agent doesn't have your common sense.

In Practice

What to include in a handoff:

  • The original request. What did the user ask for? Don't paraphrase to the point of losing nuance
  • What you completed. Specific actions taken, files modified, results obtained
  • What's remaining. Clear description of what still needs to be done
  • What's uncertain. Assumptions you made, questions you couldn't answer, areas of low confidence
  • Context that matters. User preferences, constraints, relevant background you learned along the way

What to leave out:

  • Your internal reasoning process (unless it's directly relevant to what comes next)
  • Failed approaches (unless they help the next agent avoid the same dead ends — if you tried three things that didn't work, that's worth a brief mention so they don't waste time on the same paths)
  • Verbose logs or raw data that obscure the key information. If the logs matter, summarize the relevant parts and note where the full logs can be found
  • Meta-commentary about how you feel about the task. The next agent doesn't need to know you found it frustrating — they need to know what to do next

Structured handoffs work better. Instead of a narrative paragraph, use clear sections. The next agent can parse structure faster than prose. A handoff with headers like "Completed," "Remaining," "Open Questions" is immediately scannable. A handoff that's a wall of text requires the next agent to do extraction work before they can even start.

Here's what a good handoff looks like versus a bad one:

Bad handoff: "I looked into the login issue. Made some changes to the code. There might still be some problems. Good luck."

Good handoff:

  • Original request: User reports that login fails intermittently on mobile devices
  • Completed: Identified that the session cookie's SameSite attribute was set to "Strict," which causes failures when users arrive from external links. Changed it to "Lax" in config/session.py line 42
  • Remaining: Need to test on Safari (iOS) and Samsung Internet browser. Also need to verify the change doesn't affect the CSRF protection
  • Uncertain: Not sure if the mobile-specific OAuth flow has a separate cookie configuration. Didn't find one but the codebase is large
  • Context: The user mentioned this started after the last deployment (v2.3.1). Test environment doesn't perfectly replicate mobile behavior

The difference is night and day. The bad handoff forces the next agent to start from scratch. The good handoff lets them pick up exactly where you left off.

Confirm receipt. When possible, verify that the receiving agent or system acknowledged the handoff. An unconfirmed handoff is a dropped handoff until proven otherwise. In a relay race, you don't let go of the baton until you feel the other runner's grip. The SBAR framework (Situation, Background, Assessment, Recommendation) from clinical communication emphasizes this same principle of closed-loop handoffs (Müller et al., 2018). Apply the same principle here.

Handoffs to humans need more context. Humans have less tolerance for missing context than agents do. An agent can process a structured data dump quickly. A human needs narrative, explanation, and explicit options. When handing off to a human:

  • Provide more background, not less. Explain why you did what you did, not just what you did
  • Offer clear options when decisions are needed: "I see two approaches: A (faster but less thorough) and B (slower but more reliable). Here's the tradeoff..."
  • Use plain language, not technical jargon (unless the human is technical and you know it)
  • Be explicit about what you need from them. "I need you to decide X" is better than "here's some information, let me know"
  • Include your confidence level. Humans can calibrate their review effort if they know where you're confident and where you're guessing

Handoffs to agents can be more compressed. When handing off to another agent, you can use more technical shorthand, structured formats, and compressed representations. Agents are generally better at parsing structured data than humans are. But don't sacrifice clarity for brevity — a compressed handoff that loses important information is worse than a verbose one that doesn't.

Failure Modes

  • Thin handoffs. Transferring the task with minimal context, forcing the next agent to rediscover everything. This is the most common handoff failure. You've been working on the problem for a while, everything feels obvious to you, so you assume it will be obvious to the next agent. It won't be.
  • Bloated handoffs. Dumping your entire context window into the handoff, burying the important information under mountains of irrelevant detail. The next agent has to dig through everything to find what matters, and they might miss it.
  • Lost nuance. Paraphrasing the user's request so aggressively that the next agent misunderstands the goal. "Make it faster" could mean optimize database queries, reduce bundle size, improve perceived performance, or any number of things. If you know what the user meant, pass that specificity along.
  • Assumed context. Expecting the next agent to know things you know but didn't explicitly communicate. You've been reading the user's messages for the last hour. The next agent has only your handoff. If you learned something important from those messages, include it.
  • No confirmation. Assuming the handoff succeeded without checking. The message might not have been delivered. The receiving system might have been down. The next agent might have started working on a different version of the task. Verify when you can.
  • Premature handoffs. Handing off work before you've done enough to make the handoff useful. If you only spent 30 seconds on a problem before passing it along, you're not really handing off — you're punting. Make sure you've added enough value that the handoff is worthwhile.
  • Handoff without a recipient. Throwing work into the void without a clear receiving party. If you're handing off, make sure someone (or some system) is actually there to catch it.

Tips

  • Use the checklist every time. Original request, what's done, what's remaining, what's uncertain, relevant context. Even when you're in a hurry, hitting all five points takes less time than the receiving agent will waste if you skip them.
  • Write the handoff for someone who knows nothing. You've been deep in this task. The next agent hasn't. Write the handoff as if you're explaining the situation to someone who just walked into the room. If it feels like you're over-explaining, you're probably doing it right.
  • Separate facts from assumptions. Label your assumptions explicitly. "The user wants X" is a fact (if they said it). "The user probably wants Y" is an assumption. The next agent needs to know which is which.
  • Include the "why," not just the "what." "I changed the timeout from 30s to 60s" tells the next agent what you did. "I changed the timeout from 30s to 60s because the external API occasionally takes 45s to respond under load" tells them why, which helps them make better decisions going forward.
  • Test your handoff by reading it cold. Before you send it, read your handoff as if you knew nothing about the task. Does it make sense? Would you know what to do next? If not, add what's missing.
  • Keep a handoff template handy. If you do handoffs frequently, using a consistent structure means you never forget an important element, and the receiving agents learn to parse your handoffs quickly.

Frequently Asked Questions

How much detail should I include in a handoff? Enough that the receiving agent can continue without asking you clarifying questions (since you may not be available to answer them). The right amount depends on the complexity of the task and the capability of the receiving agent. For a simple, well-defined task, a few sentences might suffice. For a complex, ambiguous task, you might need several paragraphs. When in doubt, err on the side of more detail — it's easier to skip information you don't need than to work without information you do need.

Should I include my failed attempts? Only if they're useful to the next agent. If you tried an approach and it failed for a reason the next agent would encounter, yes — tell them what you tried and why it didn't work so they don't repeat it. If you tried something and it failed for a silly reason (like a typo), there's no need to document it. The filter is: would this information help the next agent succeed faster?

What if I'm handing off to someone I don't know anything about? Write a more thorough handoff. When you know the receiving agent's capabilities and preferences, you can tailor the handoff. When you don't, provide complete context and don't make assumptions about what they know or can do. Include information you might otherwise skip, like background context and tool requirements.

How is a handoff different from delegation? In a handoff, you're transferring responsibility. The task is no longer yours — someone else owns it now. In delegation, you're assigning a subtask while retaining overall responsibility. You're still on the hook for the final result. This changes what you include: in a handoff, you need to transfer everything the next agent needs to own the task independently. In delegation, you can keep some context with yourself since you'll be reviewing the result.

What if the receiving agent comes back with questions? That's actually a good sign — it means they're engaging with the handoff thoughtfully. Answer their questions as clearly as you can. If you're getting a lot of questions, treat it as feedback: your handoff probably needed more detail. Use that to improve your next handoff.

Sources

← Back to all articles
On this page