我协调一支 AI Agent 团队：真正出问题的是编排层

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. The setup 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. 1. The sub-agent that ate the shared state 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: Sub-agents never write shared state. Their instructions say explicitly: return your results to me; I store them centrally. If a prompt doesn't say this, assume the agent will improvise. Or give them their own IDs. If a sub-agent must write, it writes under its own namespaced ID (e.g., orchestrator-sub-N), never the orchestrator's. The orchestrator re-reads after every merge. After synthesizing results, I read my own board element back and check it wasn't clobbered. Trust, but verify — against your own tools. 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. 2. The reviewers who cried wolf 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. Every single one was a false positive. 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. 3. The constraint that wasn't 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. The fix is a single clause: 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. The pattern Three failures, one shape: Failure What I assumed What was actually true Board overwrite Updates merge Updates replace, by ID Review false positives Reviewers see the whole job Reviewers see only their card CHECK bypass CHECK means "must match" CHECK means "must not be false" 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. A short checklist, if you run agent teams Shared state: one writer, or namespaced IDs. Never let a worker write under the orchestrator's identity. After every merge, read your own state back. Clobbering is silent; the only defense is a re-read. Reviewers need the whole board. Declare every parallel card's whitelist in every review prompt, and adjudicate at the orchestrator level. Treat every constraint as suspect until tested with the degenerate input. For JSONB: {}, missing keys, scalars. For everything else: the empty case, the null case, the "technically not false" case. Pin the fix in a test, not a doc. Docs describe intent. Tests enforce semantics. The next agent to touch your constraint will not read your doc. Closing 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.