Search across all documentation pages
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."
| 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 |
run_id, subgoal, entity ids, max_turns at minimum).| 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 |
ref -> content_hash (or version).| 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 |
from, to, packet_keys, status.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)| 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 |
A fact, id, constraint, or artifact reference that existed upstream but never entered the receiver's packet or readable store view.
The same content or tool work appearing multiple times in packets, stores, or traces without a single authoritative version.
It is expensive, noisy, and often leaks data. It also trains you to skip explicit contracts until something critical is buried and missed.
Shadow-compare full vs digest packets on sample runs; track specialist questions that request data already upstream; add those fields to required schema.
Prefer per-worker namespaces then a defined merge. Concurrent writes to one blob without locking create silent corruption.
They detect accidental rewrites and enable cache hits when a worker would re-fetch identical tool results.
In the host before model invocation - not only as a polite prompt instruction.
Small denormalized fields (status, short summary) can be copied for convenience. Large blobs and tool dumps should not be.
Single-agent truncation is one loop's problem. Multi-agent adds boundary authorship: who was responsible for packing the next loop.
Handoff validation failure rate and average tokens per hop. Both move when loss/dupe bugs ship.
Yes - more hops make it more important. Add cycle and refuse-path checks from the peer-to-peer page.
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.
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.
Reviewed by Chris St. John·Last updated Jul 16, 2026