Multi-agent workflows look impressive in a demo and fragile the first time real input arrives. The failure is rarely the model. It is almost always the design: too many agents, handoffs nobody specified, loops with no exit, prompts that describe a personality instead of a job. None of these are exotic problems, and all of them are cheap to fix if you catch them early.
1. Over-decomposing the problem
Six agents for a job one could handle is the most common mistake. A build starts as a "research team": planner, researcher, critic, summarizer, editor, formatter. Every handoff loses information, adds latency, and creates a new place for the pipeline to stop dead. The formatter, meanwhile, is a function — forty lines of ordinary code would do it.
A useful rule: add an agent only when you can name the specific failure it fixes, and only when that failure can't be fixed inside an existing agent's prompt. "The critic catches contradictions the writer misses" is a reason. "It felt more organized" is not. If two agents share the same context, tools, and output format, they are one agent wearing two hats.
2. Handoffs with no contract
"Send your findings to the writer" is not an instruction, it's a hope. The writer receives a wall of text with three conflicting numbers, no sense of what's missing, and improvises a structure. Define the payload as strictly as you'd define an API response.
- What goes in: named fields, not prose — a summary, a list of sources, a confidence flag.
- What the receiver may assume: is that field always present? Is an empty list a valid "nothing found"?
- Size limits: a summary of at most 200 words per source forces the sender to prioritize.
- Failure value: what to send when the agent can't do the job. A "blocked, reason: X" payload beats a creative guess every time.
Write the contract once and paste it into both prompts — the producer's output section and the consumer's input section. Half of your "the second agent ignored my instruction" bugs disappear at this point.
3. Loops that have no exit
Critic-and-writer pairs are the usual offender. The critic is told to find problems, so it finds problems, forever. Three rounds later you have paid for twelve thousand tokens of increasingly nitpicky feedback, and the text is worse than version one.
Give every cycle three things: a round limit (often two), an explicit approval token that ends the loop immediately, and a rule for what happens when the limit is reached — usually "ship the best version and log the open issues". If two agents disagree twice on the same point, a third round won't settle it. Escalate to a person or take the version with fewer factual errors.
4. Sending the entire conversation to everyone
It is tempting to hand every agent the full transcript so nothing gets lost. In practice you get agents arguing with instructions meant for someone else, budget burned on irrelevant history, and a drift toward whatever the last message happened to say.
Pass artifacts, not transcripts. Each agent should receive the smallest set of facts it needs: a task statement, the upstream output, and the constraints that apply to it. Keep one shared state object for things everyone genuinely needs — the original request, the output format, the deadline — and let everything else live in the handoff payload. When something breaks later, that separation tells you exactly where the bad value entered.
5. Prompts that describe a personality instead of a job
"You are a brilliant senior analyst with twenty years of experience" feels reassuring and does very little. It spends attention without constraining output. What changes behavior is specifying the work: input, output, rules, and stopping condition.
A prompt skeleton that holds up
- Task: one sentence, one verb. "Extract every pricing claim from the input."
- Input: what arrives and in what shape.
- Output: exact format, with a filled-in example.
- Rules: what counts as valid, how to handle ambiguity, what never to invent.
- Stop condition: when the agent is done, and what it returns if it can't finish.
Resist copying the same long preamble into five agents too. Shared context belongs in one place and gets injected at runtime; duplicated instructions drift out of sync the first time you update four copies and forget the fifth.
6. No failure path and no traces
Agents fail quietly. A tool call returns nothing, the agent continues confidently, and the error surfaces three steps later as one strange sentence in the final output. Design for it in advance:
- Validate each handoff against the contract before the next agent runs. Malformed or empty payloads should not proceed.
- Cap retries — two attempts, then stop and report.
- Decide which failures go to a person and which are acceptable to degrade.
- Log every step: input, output, tool calls, timing. Without traces you are guessing, and guessing gets expensive.
Keep a small set of test inputs — ten or fifteen covering the normal case, the empty case, and the messy case — and run them after every prompt change. A simple pass/fail count beats rereading prompts and hoping.
Start smaller than you think
The multi-agent setups that survive real traffic tend to read like plumbing: two or three agents, clear contracts between them, tight loops, and a human checkpoint at the one place where being wrong is expensive. Before the next build, run through this:
- Could one agent do this? If yes, stop there.
- Does every handoff have named fields and a failure value?
- Does every loop have a maximum round count and an exit token?
- Is any agent receiving context it never uses?
- When a step fails, who finds out, and how quickly?
Add agents when a specific failure demands one, not because the diagram looks better with more boxes. The workflow that holds up under messy input is usually the boring one.
Photo: jarmoluk / Pixabay
