AI Agent Handoff: The Six-Field Contract That Stops Loops

An agent handoff is when one AI agent passes a task, and control of it, to another agent. The new agent carries on from there. Here's the rule that matters most: treat every handoff as a data contract, not a chat message. AWS puts it plainly in its Well-Architected guidance. A handoff is a data contract before it is a workflow step.

Use a handoff when a different agent must truly take over the work. If you only need a quick answer from another agent, you don't need one.

What is AI agent handoff, and where does it fit?

A handoff moves control of a task from one specialist agent to another. The Agent Patterns Catalog defines it as moving the live conversation to a new agent and carrying the context across. It's one of three ways agents can work together.

Pattern	Who keeps control	Use it when
Handoff	The new agent takes over	A different specialist must own the rest of the job
Delegation (agent as a tool)	The first agent. It calls another, gets an answer, carries on	You need one answer, not a new owner
Supervisor	A coordinating agent routes the work	The routing is predictable, or tasks can run side by side

Handoff earns its place when:

• a billing question turns into a refund case halfway through
• a long task needs a new skill in the middle
• the job spans several areas and no one agent should own all of it

Skip it when a simpler pattern does the job. The catalog says the same thing: if one agent can handle the chat, don't reroute it. Read how multi-agent systems work if you're still choosing.

Without a clear handoff you're stuck with two bad options, the catalog says. The wrong agent bluffs through work it can't handle. Or a new agent starts cold and the customer has to repeat themselves.

How to build an agent handoff, step by step

Think of a shift change at a shop. You don't just walk out. You leave a note: what's going on, what's left to do, what the next person needs to know.

1. Make an explicit handoff tool. Give it a clear name like transfer_to_billing. OpenAI's Agents SDK works this way. A handoff to a Refund Agent shows up to the model as a tool called transfer_to_refund_agent, per the Agents SDK handoff docs.
2. Start with the simple build. LangChain's handoff docs say to use a single agent with middleware for most handoffs, because it's simpler. Save separate agent subgraphs for when you need a custom agent. Check multi-agent vs single agent before you commit.
3. Pair every tool call with a reply. When a model calls a tool, it expects an answer. LangChain returns a matching ToolMessage with each handoff so the chat history stays valid.
4. Keep the context small. Write a short task summary. Pass only the variables the next agent needs.

The core idea in LangChain is simple. The handoff tool updates a state variable like active_agent. The system reads that variable to decide who acts next.

Pro tip: Build the handoff tool before you build the second agent. If you can't say what gets passed in one sentence, the contract isn't ready.

The agent handoff contract: six fields you can't skip

A handoff without a contract is a guess in a nice suit. The Agent Handoff Protocol Spec lists six required fields.

Field	What it holds
Trigger	When the handoff fires: a stated intent, a condition in the agent's state, or a tool call
Source	The agent handing over
Target	The agent taking over
Context payload	A short task summary, where the work came from, and any rules, budget or deadline that carry over
Acceptance criteria	What the target checks before it starts: required fields, that the task is in its lane, and permission
Recovery	Where the task goes if the target says no or times out

The spec adds three guards worth copying:

• An idempotency flag, so firing the same handoff twice gives the same result.
• A dedupe_key, so duplicate handoffs get dropped.
• A loop_guard, a counter or set of visited agents that stops endless cycles.

One rule in the spec deserves a second look. If an acceptance check fails, the target must reject the handoff through the recovery path. It must not quietly patch the input and carry on. A Devwiz explainer on multi-agent systems makes the same point from the build side. Agents should check what they receive before they act on it.

Why write it all down? A handoff that only lives inside a prompt is invisible. Nobody can review it or test it. Once it's a written contract, your team can test it and change it without breaking what sits downstream.

What context should an agent handoff pass?

Passing too much is as bad as passing too little. AIPatternBook's handoff guidance calls it the "context dump fallacy". That's the belief that more raw history helps the next agent decide better. It doesn't. It burns tokens and buries the useful bits.

The Geodocs spec says the payload must not carry the full raw history when a summary will do. When you do need history, it names four ways to send it:

• Full: the whole conversation. Rarely worth the cost.
• Summary: a short brief plus the key variables. The sensible default.
• Last_k: only the last few turns. Fine for short, simple chats.
• Pointer: a reference to where the history lives, not the history itself.

So what goes in the brief? AIPatternBook lists five things: the objective, the constraints, prior decisions, the current state and the next steps. It rates prior decisions as the most valuable part. Leave them out and the next agent repeats work that's already done.

Anthropic found the same thing in its multi-agent research system. Each subagent needs an objective, an output format, guidance on tools and clear task limits. Vague briefs led agents to duplicate work, leave gaps or miss what they were looking for.

If you build on OpenAI's Agents SDK, input_filter and RunConfig.handoff_history_mapper let you control what history the next agent sees, per the same Agents SDK docs.

Stopping loops, deadlocks and dead ends

Agents can pass a task back and forth forever, like two people at a door both saying "after you". Here's how to stop it.

1. Track visited agents. Keep a set for the session and cap the total number of handoffs. The Agent Patterns Catalog warns about this exact ping-pong: agents that each think the other should own the task, with nothing to catch the loop.
2. Set timeouts. If the target doesn't respond in time, fall back. Reassign it or escalate it to a person.
3. Keep the two triggers apart. AWS's Well-Architected guidance splits agent-to-agent handoffs (a routing call) from agent-to-human escalation (a judgment call). Mix them and you either swamp people with routine tasks or let high-stakes calls slip through on autopilot.

AWS also warns what happens with no deadlock check at all. Agents that wait on each other can stall a workflow indefinitely.

Testing and watching handoffs in production

Test handoffs like any other critical path. Not as an afterthought.

• Unit tests: check the contract schema, that acceptance checks fire, and that rejected handoffs go where they should.
• Integration tests: run a full chain of handoffs, loops included, so you catch ping-pong before customers do. AI agent testing scenarios has a longer checklist.
• Metrics: AWS names handoff latency, context transfer completeness and success rate as core numbers to watch. Add handoff count per session to spot loops early.

AWS also says written handoff runbooks cut operational complexity. Set alert levels on latency and success rate before launch, not after your first bad week. Our observability guide covers how to find hidden token burn too.

Pro tip: Write a test that rejects a handoff on purpose. If the recovery path doesn't go somewhere sensible, you've found the bug before a customer did.

Why I plan the handoffs myself

Everyone gets excited about AI that spawns its own agents and hands work between them. I've tested it plenty. Here's what I keep finding. The output is better when I do the handoffs myself. When the AI hands off to itself, it cuts corners. I can't fully explain why, but I keep seeing it.

So I always keep an orchestrator. I start in plan mode with Fable or Opus and ask for a development plan. The handoffs are part of that plan. It has to decide which model takes each step, whether that's Fable, Opus, Codex or Sonnet. It has to work out what can run in parallel and what depends on what. The AI does the work. The handoffs are mine.

That's the same idea behind an AI Operating System. Each AI employee does one narrow job. The handoff contract is how your judgment moves between them, so the work scales without you in every loop. We build these with Claude Code, so the handoff rules sit in your own files, not in someone else's black box. Here's more on custom AI delivery systems built with Claude Code. Njin's breakdown of what an AI operating system for business really is puts the handoffs in the process layer, right next to the people who own them.

My three rules:

• Write the contract first. Six fields, on paper, before any code.
• Keep the brief short. A summary plus the key variables, not the transcript.
• Always add a loop guard. A visited set and a cap on handoffs.

Next step: sketch your first handoff contract on paper before you write a line of code.

James Killick

Want this built with you, not guessed at?

Firms like Polarising build agentic and multi-agent systems for the enterprise, with scoped permissions and audit trails. That suits a large IT team. If you're a founder whose judgment is the product, the job looks different.

We pull out the calls only you make today. Then we encode them into a coordinated set of AI employees that work the way you do. You own it. No vendor lock-in.

The 90-day program builds a working prototype with you and hands over ownership. It's $18,500 USD one off. Prefer to build it yourself? Platform Access is the self-serve route at $90 USD a month or $900 a year. Coaches and consultants past $1M can also look at AI consulting built for that stage.

Not sure where your bottleneck sits yet? Take the Founder Bottleneck Assessment. It takes about six minutes.

Sources

• Agent Patterns Catalog, Handoff
• Agent Handoff Protocol Documentation Spec, Geodocs
• Handoffs, LangChain docs
• Handoffs, OpenAI Agents SDK
• Design multi-agent handoff procedures with human-in-the-loop escalation, AWS Well-Architected
• Handoff, AIPatternBook
• How we built our multi-agent research system, Anthropic