Running Subagents in Parallel Without One Failure Sinking the Whole Run

Cut a token budget per branch

The first accident in parallelizing is usually contention over budget. The account-wide rate limit is a shared resource, so the more branches you add, the less room each one gets. In my case, pinning max_tokens on the branch side and capping concurrency made things stable.

Here is the allocation I use as a rough guide.

To cap concurrency itself, slot in a lightweight semaphore. It is small enough to write without pulling in a library.

function pLimit(concurrency: number) {
  let active = 0;
  const queue: (() => void)[] = [];
  const next = () => {
    active--;
    if (queue.length > 0) queue.shift()!();
  };
  return async function <T>(fn: () => Promise<T>): Promise<T> {
    if (active >= concurrency) await new Promise<void>((r) => queue.push(r));
    active++;
    try {
      return await fn();
    } finally {
      next();
    }
  };
}
 
const limit = pLimit(4);
const settled = await Promise.allSettled(
  sites.map((s) => limit(() => collectCandidates(s)))
);

Grow to eight branches and at most four ever run at once; the rest wait their turn. Treating the rate limit as a shared resource is the heart of it.

A result contract: pin down what the child returns

Most of what quietly breaks parallel aggregation is variation in the JSON a child returns. One missing key or a non-array, and the downstream for loop throws, dragging your successful branches down too. Insert schema validation on the parent side and isolate broken results explicitly as failures.

import { z } from "zod";
 
const Candidate = z.object({
  title: z.string().min(1),
  angle: z.string().min(1),
});
const CandidateList = z.array(Candidate).min(1);
 
function parseCandidates(raw: string): z.infer<typeof CandidateList> {
  const json = JSON.parse(raw); // let the caller catch the throw
  return CandidateList.parse(json); // throws if the shape is off
}

The point is to validate in the parent's aggregation phase, not inside the child. Keep the child returning plain text, and gather the trust boundary in the parent. Then "which branch was rejected, and why" collects into one log, and isolating causes gets far easier.

One branch can fail without stopping the rest

This is the center of the design. Sort the allSettled results into three buckets: success, schema violation, and transport failure.

type Outcome =
  | { site: string; ok: true; items: z.infer<typeof CandidateList> }
  | { site: string; ok: false; reason: "schema" | "network" | "unknown"; detail: string };
 
const outcomes: Outcome[] = settled.map((r, i) => {
  const site = sites[i].id;
  if (r.status === "rejected") {
    return { site, ok: false, reason: "network", detail: String(r.reason) };
  }
  try {
    return { site, ok: true, items: parseCandidates(r.value) };
  } catch (e) {
    return { site, ok: false, reason: "schema", detail: String(e) };
  }
});
 
const fulfilled = outcomes.filter((o): o is Extract<Outcome, { ok: true }> => o.ok);
const failed = outcomes.filter((o) => !o.ok);
console.log(`ok ${fulfilled.length} / failed ${failed.length}`);

At this point candidates for the three successful sites are already in hand. The one that failed sits isolated in failed, and the run moves forward. The serial-era "site three takes everyone down" can no longer happen structurally.

Where to route a failure

Retrying every failure the same way mixes "failures that heal if you wait," like a rate-limit overrun, with "failures that never heal," like a schema violation, and the pointless retries squeeze the limit further. Routing by reason is safer.

A dead-letter need not be elaborate. In my setup I append the failed site ID, reason, and raw response as a one-line JSON to a log file, and keep a separate morning batch that picks up only those. Rather than trying to recover everything perfectly on the spot, deciding to "lock in what you got and record the misses for later" is, in the end, what breaks least in unattended nightly runs.

How much it actually changed

Here are rough numbers from running the same candidate collection 20 times each, serially and in parallel, on my four-site setup. Environments differ, but it is useful for the trend.

What stands out is that the capped row is a few seconds slower than uncapped yet drops the 429 rate to near zero. For a handful of seconds, you erase the time lost to retries and the risk of overrunning the limit. In a nightly batch, a "speed that does not crash" is worth more than peak speed.

Operational notes the docs do not cover

A few small things that only became clear after running this for a few months.

First. Promise.allSettled waits for every branch to finish, so a single pathologically slow branch drags the whole thing. Wrap each worker in an AbortController timeout and fail slow branches into the network bucket yourself, so the slowest single branch cannot hold the whole run hostage.

Second. Emit logs in "the same one-line format for both success and failure." If successes are verbose and failures terse, the formats do not line up exactly when you need failure analysis most.

Third. Keep the concurrency number out of the code and in an environment variable. Rate limits move with your plan and account state. Making it "change one number when the limit changes" saves you from scrambling at midnight. I had this value hardcoded once and missed out on a limit increase for a while.

The next step

Pick just one independent process you currently run serially, and swap it to Promise.allSettled with concurrency two. Fixed budgets and schema validation can wait until that one is stable. Parallelize small, let yourself get used to handling partial failure, then raise the count — that order grows an automated pipeline the most calmly.

If you have been wrestling with the same naivety in a nightly batch, I hope this gives you a thread to pull on for your own design.