Home / Several agents and adversarial checking

Making a large scale fan-out hold together

A bulky deliverable handed to a single agent gets cut off by an output size limit with nothing written at all: split by axis, have each agent write to its own file, respect the documented cap of sixteen agents active at once and one thousand agents in total on a single run, a single call accepting up to 4,096 items that the runtime itself schedules under that cap, then verify by comparing the expected files against what actually exists on disk rather than taking the agents' word for it.

A single agent tasked with writing an over-long deliverable gets interrupted by an output size limit, and nothing gets written to disk: the task looks impossible when the real problem lies in the splitting. The fix fits in one sentence, one agent per axis, each writing its own file, so that the limit only ever bears on a single file at a time rather than on the whole deliverable.

The documented cap

Claude Code caps the number of agents active at the same time at sixteen, a figure that drops if the machine has fewer processors available, including inside a container with a limited number of cores. A second cap, distinct from the first, limits the total number of agents launched across an entire run to one thousand, precisely to stop a runaway loop from launching agents endlessly. These two counters must not be confused: the first bounds what is running at a given instant, the second bounds the cumulative total over the whole duration of the work. A third figure changes the practical picture: a single parallel() or pipeline() call accepts up to four thousand and ninety six items, and the runtime itself schedules them under the cap of sixteen, with no manual step, a longer submission being simply rejected with an error rather than silently truncated. Splitting manually into successive waves, each wave checked before the next one starts, keeps its use, but as a choice for verifying the work in batches rather than as the only way to stay under the concurrency cap.

Verify the disk, not the report

An agent that claims to have written its file can be wrong, about its own output path or about the content actually produced. The discipline that closes the loop is to write, before launching the fan-out, the exact list of expected files, then compare it afterwards against what genuinely exists on disk, never against the reports the agents themselves send back.

# liste attendue, écrite avant le lancement
cat > attendus.txt < obtenus.txt
diff attendus.txt obtenus.txt

One last reflex saves budget on a large volume of similar calls that do not need an immediate answer. The Batch API processes this kind of work asynchronously with a fifty percent discount on token cost, on a rate quota separate from live calls. It suits a fan-out that is already written and ready to run in one go, not work where each step depends on the result of the one before.

These three disciplines combine in the reverse order of their discovery. You first isolate each agent in its own worktree, then respect the concurrency cap through waves, and finally verify on disk what the fan-out actually produced, never what the agents said about it.