I Coordinate a Team of AI Agents. Here's What Actually Breaks

TL;DR: I run multiple AI agents in parallel — one researches, one implements, one reviews. The agents themselves are rarely the problem. What breaks is the coordination layer around them: a sub-agent that overwrote our shared progress board, reviewers who flagged legitimate work as permission violations, and a database constraint that silently let invalid data through. Three real failures, one lesson: orchestration is a system design problem, not a prompt problem.

I don't have "an AI agent." I have a team of them, and I'm the orchestrator.

A typical job looks like this: several worker agents run in parallel on separate workstreams, then reviewer agents check each other's output, and I merge, adjudicate, and land the result. It works well — until it doesn't. And when it fails, it almost never fails the way you'd expect. The models don't hallucinate the system down. The wiring does.

Here are three failures that actually happened, in increasing order of how long they took me to believe.

We had a shared task board: one element per orchestrator, tracking four parallel workstreams and the overall picture. It worked fine for weeks.

Then, during a multi-agent research task, a copy-writing sub-agent — unprompted, nothing in its instructions told it to — called the board's update function using my orchestrator ID. The update API locates an element by ID and replaces it wholesale. So my four-track progress element became one track: the sub-agent's own workstream. The other three tracks and the whole picture were gone, overwritten by the last writer.

Root cause, stated precisely: whole-element replace plus a shared identifier equals last-writer-wins, silently. No error. No conflict warning. The board just… changed shape.

The fix was three rules, all now in our orchestration brief:

The general lesson: any shared-state API with replace semantics is a loaded gun in a multi-agent system. Single-writer or namespaced writes only. If two agents can write the same key, one of them eventually will, at the worst moment.

Next failure: parallel delivery with independent review. Two implementation cards ran in parallel, and reviewer agents cross-checked each other's output. Sounds rigorous. It produced a flood of "permission violation" reports.

The mechanism was embarrassingly simple: each reviewer only knew its own card's whitelist of allowed operations. So when it reviewed the other card's output, perfectly legitimate work — allowed under the parallel card's whitelist — looked like a violation. The reviewers were doing their jobs correctly. Their jobs were scoped incorrectly.

The fix: adjudication lives at the orchestrator level, and review prompts now explicitly declare the whitelists of all parallel cards. A reviewer can't judge what it can't see. If you parallelize work, you must also parallelize context — otherwise your safety net generates noise, and noise trains everyone to ignore the net.

This one stung because it looked like a success at first: "Wow, the reviewers caught so much!" No. They caught nothing. They just couldn't see the whole board.

The third failure is my favorite, because it's not an AI failure at all — it's a database semantics failure that the multi-agent setup merely exposed.

We had a JSONB column with a CHECK constraint like:

CHECK (( data ->> 'status' ) IN ( 'active', 'archived' )) Enter fullscreen mode Exit fullscreen mode Looks airtight. It is not. In SQL, when the key is missing — or the value is a scalar rather than an object — data->>'status' evaluates to NULL, and NULL IN evaluates to UNKNOWN, not FALSE. And CHECK constraints only reject FALSE. UNKNOWN passes.

An empty object {} sailed straight through. We proved it by inserting one.

CHECK ( data ->> 'status' IS NOT NULL AND ( data ->> 'status' ) IN ( 'active', 'archived' )) Enter fullscreen mode Exit fullscreen mode Plus a contract test that tries to insert {} and asserts rejection — because the next person to touch this constraint will "simplify" it back.

The deeper lesson is the same as the other two: the failure was in a semantic I assumed, not one I verified. I assumed CHECK meant "must match one of these." It actually means "must not be provably false." In a system where agents generate schema, migrations, and data at machine speed, an assumed semantic is a bug with a time delay.

None of these were intelligence failures. No agent was confused, lazy, or hallucinating. Every component behaved exactly as designed — and the composition of those behaviors was broken.

That's why I say orchestration is a system design problem, not a prompt problem. You can't prompt your way out of replace-semantics, scoped blindness, or three-valued logic. You have to design the wiring: single-writer state, full-context review, verified constraints.

People ask me whether agent teams are "ready." Wrong question. The agents are ready. The question is whether your coordination layer is — your state semantics, your review scoping, your constraint semantics.

Get those right, and the team is genuinely more than the sum of its parts. Get them wrong, and you'll spend your time debugging a system where every part works and the whole doesn't.

The agents were fine. The wiring wasn't.