agentsop-map-reduce-fanout

Map-Reduce / Dynamic Fan-Out · SOP

Pattern: results = reduce(combine, parallel_map(f, L)) where f is one or more LM calls. The only reason to fan out is that latency or throughput matters more than the cost of doing it. The only reason to fan in is that the consumer wants one answer, not N.

Source posture: claims grounded in primary docs and 2026 production write-ups, cited inline with short tags resolved in the citation index.

1. 何时激活 (Activation Rules)

Activate this skill when any of these is true:

• The task description contains "for each X, do Y" where Y involves an LM call, a retriever hit, or any I/O-bound step costing >100ms.
• The coder is about to write a for item in items: result = llm(item) loop and the items are independent (no item depends on the previous result).
• The codebase already has asyncio.gather(...), ThreadPoolExecutor(...), Send(...), Process.hierarchical parallel branches, or crew.kickoff_for_each(...) and the question is how to use them safely.
• The user mentions any of: "summarize N docs", "rank top-K candidates", "vote across M models", "ensemble", "parallel agents", "multi-query retrieval", "scatter-gather", "fan out".
• A LangGraph graph is throwing InvalidUpdateError on a key two parallel branches write to (see OP-3 cross-link in skill O5 state-reducer).
• A LangGraph Send-based fan-out is hitting GRAPH_RECURSION_LIMIT or rate-limit 429s because all N workers fired at once [aipractitioner/scaling].

Do not activate when:

• N is statically 1 or 2 (just write the calls inline; setup cost ≥ win).
• Items depend on each other (sequential reasoning, chain-of-thought across docs) — fan-out destroys the dependency.
• The downstream code only needs the first successful answer — use asyncio.wait(..., return_when=FIRST_COMPLETED), not gather.
• The "fan-out" is into a single batched API call (e.g., embedding 100 strings in one OpenAI request). That's a batched single call, not map-reduce. Use it; it's cheaper.