Avoiding Context Loss and Duplication Across Agent Handoffs
Silent context bugs are the most common multi-agent failure mode. The specialist never receives an id the orchestrator thought was "obvious," or every hop pastes the same 20-page tool dump until the window collapses.
Use this cheatsheet before launch and when debugging "the second agent went stupid."
How to Use This Cheatsheet
- Walk A when designing packets; B when implementing stores and merges; C when reviewing traces after incidents.
- Tick items only when enforced in code or tests, not as slideware.
- Pair with Context Handoff: Passing State Between Agents Cleanly for the positive recipe.
- Re-check after adding a new specialist or lengthening pipelines.
A - Prevent Loss at the Boundary
| Check | Why it matters | Fail signal |
|---|---|---|
| Required ids listed in schema | Models invent substitutes when ids vanish | Wrong ticket/order acted on |
| Validate packet before invoke | Fail closed beats silent omission | Specialist starts with empty inputs |
| Subgoal is explicit | Receiver must not reverse-engineer intent from history | Agent redoes prior stage |
| Constraints travel with work | Policy is not ambient | Disallowed action appears mid-chain |
| Success fields named | Receiver knows what to return | Orchestrator gets essay without status |
| Budget included | Nested loops need local caps | Worker runs until global death |
| Secrets redacted by role | Least privilege at data layer | Low-trust agent logs API keys |
| User text digested when needed | Full paste is not always required | PII sprawl across tools |
- 1. Schema lists required keys (
run_id,subgoal, entity ids,max_turnsat minimum). - 2. Builder unit tests cover missing-key rejection.
- 3. Digests include open questions and non-goals, not only successes.
- 4. Human escalations preserve the same packet fields the next agent would need.
B - Prevent Duplication and Bloat
| Check | Why it matters | Fail signal |
|---|---|---|
| Artifacts stored once | Copies diverge | Two "final" drafts fight |
| Packets carry refs | Windows fill with JSON | Token spikes per hop |
| Merge uses stable keys | Fan-out needs identity | Dedupe impossible |
| Tool results not re-fetched blindly | Cost and drift | Same search 5 times |
| History is status-sized | Audit without graveyards | Trace larger than task |
| Schema version on writes | Old writers vs new readers | Ghost fields / drops |
| Idempotent handoff ids | Retries create clones | Duplicate side effects |
| Summarize before re-handoff | Long chains amplify noise | Quality falls with depth |
- 5. Artifact index maps
ref -> content_hash(or version). - 6. Merge functions define conflict policy (concat, vote, highest confidence) - never accidental last-write-wins.
- 7. Workers check cache/index before re-running expensive tools.
- 8. Max packet size / max transcript inclusion enforced in host.
C - Detect Problems in Traces
| Signal | Likely cause | First fix |
|---|---|---|
| Specialist asks for id already known upstream | Loss | Required field + validator |
| Identical search queries across agents | Duplication | Shared artifact cache |
| Context tokens grow linearly with hop count | Transcript dumping | Refs + digests |
| Status missing or free-form | Weak return contract | Enum validation |
| Contradictory artifacts after fan-in | Merge gap | Explicit merge rules |
| Retry doubles charges or emails | Non-idempotent handoff | handoff_id + idempotency keys |
| Deep handoff depth, no new artifacts | Cycle / thrash | Depth cap + progress token |
| PII in unexpected worker logs | Over-share | Redaction by role |
- 9. Every handoff span logs
from,to,packet_keys,status. - 10. Dashboard tracks handoff depth, validation failures, and duplicate artifact writes.
- 11. Eval suite includes "drop field" and "duplicate artifact" adversarial cases.
- 12. On-call runbook names the packet schema owner.
Quick Decision Tree
Is the next agent missing a fact the previous agent knew?
yes -> loss: add required field + boundary validation
no -> Is the same fact present N times in context?
yes -> duplication: store once, pass ref, tighten merge
no -> Is quality falling only after hop 2+?
yes -> digest quality / budget / wrong specialist
no -> look outside handoff (tools, model, prompt)Mini Anti-Patterns
| Anti-pattern | Replace with |
|---|---|
| "Just forward the whole chat" | Packet + digest + refs |
| "The model will notice the id in there somewhere" | Required structured field |
| "Each agent keeps its own final_draft.md" | Versioned artifact key in shared store |
| "Retry the handoff by starting a new run_id" | Same run_id, new handoff_id, idempotent apply |
| "More context always helps" | Measured digests; drop dead tool dumps |
FAQs
What is context loss in a handoff?
A fact, id, constraint, or artifact reference that existed upstream but never entered the receiver's packet or readable store view.
What is duplication across handoffs?
The same content or tool work appearing multiple times in packets, stores, or traces without a single authoritative version.
Why not always send the full transcript?
It is expensive, noisy, and often leaks data. It also trains you to skip explicit contracts until something critical is buried and missed.
How do I know a digest omitted something important?
Shadow-compare full vs digest packets on sample runs; track specialist questions that request data already upstream; add those fields to required schema.
Should fan-out workers share one writable document?
Prefer per-worker namespaces then a defined merge. Concurrent writes to one blob without locking create silent corruption.
How do content hashes help?
They detect accidental rewrites and enable cache hits when a worker would re-fetch identical tool results.
Where do I enforce max packet size?
In the host before model invocation - not only as a polite prompt instruction.
Is duplication ever acceptable?
Small denormalized fields (status, short summary) can be copied for convenience. Large blobs and tool dumps should not be.
How does this differ from ordinary context-window management?
Single-agent truncation is one loop's problem. Multi-agent adds boundary authorship: who was responsible for packing the next loop.
What metric should go on the team dashboard first?
Handoff validation failure rate and average tokens per hop. Both move when loss/dupe bugs ship.
Can peer-to-peer graphs use the same checklist?
Yes - more hops make it more important. Add cycle and refuse-path checks from the peer-to-peer page.
What is the fastest fix when an incident is live?
Patch the packet builder to hard-require the missing field, fail closed if absent, and re-run from a checkpoint - do not only "remind" the model in prose.
Related
- Context Handoff: Passing State Between Agents Cleanly - packet recipe
- Architecture Guide: Designing a Multi-Agent System's Communication Contract - formal schemas
- Orchestrator-Worker Patterns for Coordinating Specialist Agents - dispatch merges
- Multi-Agent Architecture Basics - first system
- Peer-to-Peer Agent Collaboration Without a Central Orchestrator - multi-hop risks
- Multi-Agent Architecture Best Practices - section practices
- Multi-Agent Handoff: Specialist Agents Passing Work to Each Other - handoff model
Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana
@solana/web3.js+@solana/spl-token.