Vendors sell complexity. We publish the ceiling.

Multi agent LLM orchestration is the control layer that coordinates multiple LLM-driven nodes (agents) toward one outcome. In production it is three artifacts: a graph or pipeline file (nodes, edges, typed state), an eval harness running on a fixed golden set, and an audit trail of every node transition. At PIAS we ship the orchestration as source code in your repo on main, with a published ceiling on how many agents are allowed to talk to each other. That ceiling is 8 edges, a 3-turn handoff budget encoded as a typed state field, and no more than 2 models in the critical path.

The MAST failure taxonomy (Cemri et al., 2025, arXiv 2503.13657) catalogued 14 failure modes in production multi-agent LLM systems, with inter-agent misalignment as the single most common and infinite handoff loops in the top three. Those failure modes scale with the number of edges and the number of possible agent-to-agent transitions. A numerical ceiling caps the failure surface directly. Prose rules like 'write clearer specifications' do not; a Pydantic field with ge=0, le=3 does. The ceiling is an opinion and we defend it as one.

It is a Pydantic-constrained int field on the state object (CaseState), defaulted to 3, bounded between 0 and 3. Every production multi agent LLM graph we ship has it. It is decremented in one place: the after-hook record_transition in audit.py, and only when the transition is agent-to-agent (both source and destination are in AGENT_NODES). When it reaches 0, a conditional edge routes to a deterministic escalation node that writes a budget_exhausted audit row and returns a human-routing payload. There is no retry after the budget exhausts; that is the whole point of the field.

Three is the smallest number that allows a primary-then-fallback-then-review pattern to complete under normal conditions and still catches a loop before the 4th hop. On Upstate Remedial Management, where regulatory exposure on a wrong email is the failure cost, we shipped with 3. On Monetizy.ai, where the failure cost is a reschedule of an email campaign, we also shipped with 3. Two starves the fallback path on legitimate primary failures. Five lets loops accumulate enough context to look like progress. Three is an empirical choice from shipped systems, not a theorem. It is also a single number in one config file, so your team can tighten it to 2 on any engagement if the domain calls for it.

max_iterations as typically configured is a retry ceiling on a single agent, usually set in a prompt or a runtime config. It does not travel with the state object across handoffs, it does not enforce determinism on exhaustion, and it does not write an audit row that an on-call engineer can query. handoff_budget is a typed field on the state object that every node reads and one hook decrements. When it exhausts, a named node runs, a row lands in Postgres, and the alert can query for budget_exhausted = TRUE. max_iterations is a loop break; handoff_budget is a contract term.

The escalation node runs. It is deterministic and has no LLM call. It writes a row to audit_rows with budget_exhausted=TRUE, emits a CloudWatch or Datadog event on the budget_exhausted metric, pages the on-call if the metric exceeds its threshold, and returns a response payload that routes the case to a human queue (for Upstate Remedial Management: a Zendesk ticket with the case context). The regulatory audit trail stays intact (every case has a row) and the customer is never left with a silently-hallucinated outcome. Two failed models is an incident; an unanswered customer is a lawsuit.

A ceiling on edges does not stop agentic work; it forces the design to allocate edges deliberately. Across five shipped systems, the edge counts we ended up with were 4, 6, 8, 5, and 7. None exceeded 8. Two of those systems (OpenLaw, PriceFox) do real multi-step reasoning with retrieval, scoring, and critique. The work fits under the ceiling because the graph is designed around named outcomes per node rather than open-ended agent chatter. If your problem shape genuinely needs a 15-edge graph, the correct move is to split the problem into two orchestrators with a queue in between, not to raise the ceiling.

Yes. We use LangGraph when the state is a typed conversation, Pydantic AI when the state is a scored pipeline (Monetizy.ai shape), and a custom DAG when the state is a tree (OpenArt scene graph). In every case the state object is a Pydantic BaseModel, handoff_budget is a field on it, the decrement lives in one hook, and a conditional edge or gate routes to a deterministic escalation node on 0. The framework choice is downstream of the problem shape. The ceiling is not.

Two checks in .github/workflows/evals.yml. One, a graph_walker script that imports graph.py, walks the compiled graph, and asserts that len(graph.edges) <= 8 and max_depth(graph) <= 4. Two, a unit test that constructs a CaseState with handoff_budget=0 and asserts the router routes to escalation. Both checks are required status checks on the main branch, so a PR that widens the graph past the ceiling cannot merge. The ceiling is a branch-protection rule, not a style guide.

The model_adapter.py file exports pick_primary() and pick_fallback(). Primary and fallback are chosen per engagement based on the provider mix the client already runs (Bedrock + OpenAI, Vertex + Anthropic, Azure + Bedrock). The cap at 2 in the critical path exists because a 3rd model does not add resilience that a primary-plus-fallback with the right rubric does not already cover, but it does add a 3rd vendor contract, a 3rd set of rate limits, and a 3rd audit surface. If a customer needs provider diversity for regulatory reasons (EU data residency, SOC 2 scope), the 3rd model goes in a separate graph with a queue, not into the critical path of the same orchestrator.

Two to four weeks for most systems we have retrofitted. Week 1 is reading the existing graph, counting edges, scoring it against the ceiling, and writing the CI asserts so further growth is capped. Week 2 is adding handoff_budget to state, moving the decrement into one hook, and wiring the deterministic escalation node. Week 3 is retrofitting the audit row schema if it is not already there. Week 4 is the runbook and the 90-minute on-call handoff. If the existing graph is already under 12 edges, it is usually 2 weeks. If it is a 30-edge tree of sub-agents, the honest answer is to split it and that is closer to 6 weeks.