DEV Community

Taiki Mishima
Taiki Mishima

Posted on

What I Cut First When Reviewing a Multi-Subagent AI Architecture

When debugging why a multi-agent system keeps breaking in practice, I rarely start by editing a prompt. First I cut the extra agent boundaries, the un-gated triggers, and the stale config paths that let failures accumulate silently.

Most multi-subagent setups look clean on a whiteboard: a planner delegates to a researcher, a coder, a reviewer, and a deployer. In practice, every arrow between boxes is a place where state drops, context bloats, retries multiply, and evaluation drifts away from what actually runs. When looking at a failing agent architecture, I skip swapping orchestration frameworks or tuning phrasing and look for what can be deleted, turned into a plain deterministic tool, or folded back into one bounded loop.

Here is what I inspect first, using three failures from an internal agent runner I build and operate (mitama, which is my own in-development system rather than a client product) and the exact structural changes that stopped them.

What breaks first in multi-subagent systems?

Before reading individual system prompts, I trace four things: where long-lived state lives, who is allowed to trigger external side effects, how context size is bounded, and whether the evaluation setup reads the exact same code and data as production.

Inspection Target Failure Signal What I Cut or Fold
Long-lived coordinators Compaction loops, "Prompt is too long", child agents left idle for days Cut perpetual sessions; rotate at 60% context against one handoff file, or fold into one loop
Parallel fan-out triggers Retries or non-draft pushes burning CI/API quotas overnight Cut autonomous trigger rights; gate side effects behind explicit state and cancel-in-progress
Always-loaded context & sync jobs Prompt bloat (>40k chars), blind full-corpus upserts, logging timeouts Cut stale instructions and unhashed full syncs; move telemetry off the critical path
Automated evals High scores alongside broken real outputs, or scores stuck below threshold Cut proxy-only checks; calibrate against known-good and known-broken baselines

Everything else in a review flows from those four checks. Below are the three core questions I use to diagnose a multi-agent setup, along with what actually failed in my own harness (mitama).

When should a multi-subagent system be folded back into a single loop?

Fold subagents back into one loop whenever they share the same working context, pass free-form prose back and forth, or rely on a single long-lived coordinator to remember what happened across runs.

Between November 8 and November 13, 2026, my main orchestrating agent (running Opus with four child subagents) stopped producing real work. Its last completed step was on November 8 at 14:06. By the time I caught the stall five days later, the coordinator had accumulated roughly 9,000 activity entries, gone through repeated context compactions, and died on "Prompt is too long". All four child agents stayed idle the entire time.

Two design mistakes caused that five-day outage:

  1. One long-lived coordinator carried all orchestration history. Because the lead agent stayed alive across days of subagent updates, tool outputs, and compactions, its context window became a single point of failure. Once compaction could no longer compress the thread, the agent became unresponsive instead of handing off cleanly.
  2. The health check tested liveness instead of progress. A parent heartbeat checked whether the agent session existed, not whether its latest activity showed progress or an error loop. On top of that, a separate cleanup plugin ran every five minutes and archived child agents attached to a parent label if they sat idle for 20 minutes. When a parent session got archived, its child agents were swept away with it, killing background builds and tests in flight.

To fix it, I stopped treating the coordinator as an immortal process:

  • Rotate at 60% context usage. Instead of waiting for compaction to fail, the coordinator tracks LastUsage against the context ceiling and hands off to a fresh session at 60%, using a single handoff document as the source of truth rather than chat history.
  • Check activity state in the heartbeat. The 60-minute heartbeat inspects the latest activity log; if it sees "Prompt is too long" or consecutive compactions, it forces an immediate rotation instead of reporting the session as alive.
  • Explicitly decouple or fold short-lived subagents. When a subtask does not require strict isolation of permissions, model tier, or failure blast radius, keeping it inside one bounded loop (plan -> act -> observe -> decide) eliminates the handoff and parent-child lifecycle bugs altogether.

A second agent is only justified when you have a concrete isolation requirement: for example, you want a read-only reviewer that cannot touch write tools, you need a cheaper model for a high-volume map step, or a subtask runs in a separate worktree. If two agents share the same permissions, the same files, and the same model, splitting them just gives you two context windows to desynchronize.

How I decide what stays a tool vs. becomes a subagent

When mapping an existing architecture, I apply three tests to every agent box on the diagram:

  • Does it have a deterministic contract? File diffing, schema validation, database upserts, and test execution do not need an LLM reasoning loop around them. Make them deterministic tools called by the main loop.
  • Does it need independent memory? If the step needs 20 lines of input and returns a structured JSON verdict, a stateless function call or single-turn tool invocation works better than a persistent subagent thread that accumulates stale history.
  • Can a failure in this box silently hang the parent? Every asynchronous child introduces timeout, orphan, and state-reconciliation code. Unless parallelism cuts wall-clock time meaningfully or isolation is mandatory, sequential execution inside one loop is cheaper to maintain.

How do you stop parallel subagents from blowing through CI or API budgets?

You stop budget blowups by removing autonomous trigger privileges from subagents and putting hard state gates in code or workflow definitions, never by adding "please be mindful of cost" to a system prompt.

On November 7, 2026 at 14:22 JST, GitHub Actions blocked all jobs on my repository with "Usage blocked" after hitting the $10 monthly budget cap. That month had already reached 557 CI runs, with 140 pull_request triggers firing on November 7 alone.

Tracing the logs showed why. Several parallel coding subagents wanted CI feedback before reporting back, so they opened pull requests without the draft flag and pushed repeated incremental fixes to the same branches. Every push spun up more than 20 jobs, including full database service containers. At the same time, a scheduled wake job was running on macOS runners (which carry a 10x billing multiplier), accounting for 57 of the previous 200 workflow runs.

The subagents were following their instructions: write code, verify it, and fix failures. The architecture lacked a gate between "subagent pushed a commit" and "spin up 20 containers on paid runners."

Here is what I changed in the repository and agent guardrails to stop the bleed:

  1. Gate heavy workflows behind explicit review states. Heavy CI jobs now run only on ready_for_review, an explicit run-ci label, or manual dispatch. Routine subagent branches stay in draft mode.
  2. Cancel redundant runs automatically. Adding concurrency with cancel-in-progress: true stops older pushes on the same branch from finishing after a newer commit arrives.
  3. Skip CI on documentation-only edits and restrict expensive runners. Docs changes no longer trigger test matrices, and the wake workflow was restricted to main instead of firing across branches on 10x runners.
  4. Block full-suite runs inside subagent shells. Subagents run targeted unit tests for the files they touched; full test suites wait for the merge gate.

The general rule for any multi-agent architecture is simple: an LLM loop should never hold an unthrottled trigger for an external meter. Whether the meter is GitHub Actions minutes, LLM token spend, email sends, or database writes, the cap belongs in the deterministic wrapper around the tool. Rate limits, max_retries, idempotency keys, and dry_run defaults are architecture concerns. Prompts cannot enforce budgets reliably when an agent hits an unexpected error loop.

Why do automated agent evals pass while the real workflow breaks?

Automated evals pass on broken systems for two reasons: the production runner is using different code or configuration than the eval expects, or the eval grades proxy metrics that miss the actual failure mode.

Both happened in my own setup within the same two-week period.

Failure mode A: Silent drift between production and the repo

On November 2, 2026, while auditing why my self-improvement loop (RSI) was repeatedly ending in no-ops, I found five separate layers of drift running simultaneously:

  1. Production was 198 commits behind main. The symlink serving the live runner pointed to a side branch (rsi/local-edits-1028) left over from an earlier debugging session. I kept reading and improving main, while production executed older logic.
  2. 54 predictions had never been graded. The scoring pipeline ran, but missing deadline handling left historical predictions ungraded, hiding real accuracy.
  3. A sync script re-sent 1,289 files every 10 minutes. Without content hashing, an audio-capture uploader attempted to upsert all 1,289 files on every 10-minute tick. Each failed file appended an error line, generating 69,000 error lines and pinning the friction log at its 2,500-line ceiling so new issues could not even be recorded.
  4. Telemetry blocked the critical path past the 30-second timeout. An MCP server awaited a database insert inside a finally block before returning responses, pushing tool latency to 30 to 37 seconds and tripping Claude's 30-second connection timeout.
  5. Always-loaded context had bloated to 73,781 characters. Rules, skill descriptions, and memory indexes loaded on every turn had crept past 73k characters before I trimmed them to ~39,988 characters (and two weeks later, by November 16, it had already crept back up to 44,262 characters against a 40,000-character limit).

I fixed those with mechanical invariants: pinning the live runner to origin/main with git pull --ff-only and exec on entry so stale branches cannot linger; comparing sha256 digests so only changed files upload; moving logging into EdgeRuntime.waitUntil off the response path; and putting a hard 4-day cutoff on prediction grading.

Failure mode B: An eval that gave 96/100 to an unreadable screen

Even when production and the test runner match, proxy graders lie.

On October 28, 2026, an automated UX evaluator (jev) gave a newly built status page 96/100 on desktop and 95/100 on mobile. When I opened the actual rendered screenshot at 1440x900, the page was unusable: internal jargon everywhere, tiny low-contrast text, and 50 lines of raw HTTP logs pushed to the right with no plain summary at the top.

Why did it get 96/100? Because the grading script passed numeric DOM JSON (overflow checks, pixel sizes, contrast ratios, console error counts) to a text-only evaluator that never looked at an image. To the JSON schema, "nothing overflowed and font sizes met minimums" looked like perfection.

A day earlier, on October 27, I hit the opposite calibration bug on a browser UI review: 14 behavioral checks were green, yet vague grading prompts like "is this UI good?" capped even a known-good ideal state at 61 to 73 points (while a deliberately broken state scored 12 to 22). Until I calibrated every question against an explicit good baseline (A) and broken baseline (B) and replaced vague questions with concrete observable conditions, a 90-point pass threshold was unreachable.

Both problems pointed to the same fix:

  • Never trust an uncalibrated eval. Before using any LLM-as-a-judge score as a gate, run it on one known-good example and one known-bad example. If the good example cannot clear 90, fix the rubric before tuning the agent.
  • Inspect the actual artifact alongside telemetry. If your agent produces UI, check the rendered first viewport (1440x900 and 390x844). If it writes SQL or emails, sample the raw artifacts alongside pass/fail booleans.

What I inspect in a 14-day architecture review

In the 14-day architecture review I offer, the work follows the same sequence I used to clean up my own setup:

  1. Map every agent, state store, and external trigger. I trace where context enters, where it gets compacted or dropped, and what happens when a step times out or retries twice.
  2. Identify every subagent that can become a tool or a loop step. Most multi-agent codebases improve as soon as 40 to 60 percent of the orchestration glue is removed.
  3. Locate missing cost and safety gates. I mark every API call, CI trigger, database write, or outbound message that currently relies on prompt wording instead of code-level bounds.
  4. Check live-vs-eval alignment. I verify whether your eval suite tests the actual production config and whether your grading rubric is calibrated against real failures.
  5. Write the target single-loop spec and cut list. You get a written architecture map, diagnosis, target single-loop design with explicit tool contracts, and prioritized next steps ordered by risk and engineering effort.

Who this review is not for

To avoid wasting your time or mine, I turn down work that falls outside a bounded written review:

  • Ongoing implementation or full rebuilds. I do not take recurring engineering retainers or production build contracts. Your team keeps full ownership of writing and shipping the code.
  • Greenfield ideation. If you do not yet have an agent codebase, prompt/config set, failure logs, or concrete system design on paper, there is nothing to audit.
  • Audits requiring live production credentials. I review exported repositories, redacted logs, and architecture notes asynchronously. I do not log into live customer databases or production API accounts.
  • Framework shopping. If you mainly want someone to compare LangGraph, CrewAI, AutoGen, and custom SDKs in the abstract, you do not need a $1,400 review. The failure modes above happen in all of them.

Background and availability

I am Taiki Mishima, based in Japan, an undergraduate at Rikkyo University currently on leave (expected graduation March 2029). I maintain my own multi-agent runner (mitama) and allocate around 5 hours per week to written architecture reviews, communicating asynchronously in English. Terms are fixed at $1,400 USD for a 14-day turnaround with one revision round.

https://www.upwork.com/services/product/development-it-an-ai-agent-architecture-review-fold-multi-subagent-sprawl-into-one-loop-2118526378880612216

Top comments (0)