Home › Claude › Agent › Parallel

⏸️ Parallel workflow: many tasks at once

When tasks don't depend on each other, there's no need to wait in line. A parallel workflow starts them all together, waits for them to finish, and then combines what they found.

• Beginner
• ⏱ 20 min
• General workflow pattern

What is it?

Parallel execution means running several independent tasks at the same time instead of one after another. A coordinating program (1) splits the work, (2) starts every task, (3) waits for all of them, and (4) combines the results into one answer.

Independent task

A task that doesn't need any other task's result to start.

Concurrency

Having several tasks in progress at once. While one waits for Claude to reply, the others keep going.

Fan-out / fan-in

Fan-out: send work to many tasks. Fan-in: collect their results back together.

Aggregator

The step that combines all the results into the final output.

Timeout

The longest you're willing to wait for a task before giving up on it.

Rate limit

The maximum number of requests an API accepts from you in a period of time.

Sequential and parallel compared

Why is it important?

• Speed: three 20-second tasks take about 20 seconds in parallel instead of 60.
• Focus: each task looks at one subject, which often gives better results than one huge request.
• Confidence: running the same check several times and comparing the answers (called "voting") can make results more reliable.

Real-world analogy

How does it work?

1. Check independence: make sure no task needs another task's result.
2. Distribute: create one task per item (one per competitor, document or question).
3. Run together, with a limit on how many run at once and a timeout for each.
4. Collect all the results, including which tasks failed.
5. Combine them into the final answer and point out any gaps or disagreements.

There are two common versions. Sectioning gives each task a different piece of work. Voting gives every task the same piece of work and compares the answers.

Workflow diagram

Try it: sequential and parallel side by side

Practical example: researching three competitors

A small e-scooter start-up wants a quick comparison of three competitors from a file of collected notes.

1. The program starts three Claude calls together, one for each of Acme Scooters, Bolt Rides and CityGlide.
2. Each call returns 5 bullet points on pricing, strengths and weaknesses.
3. If one call fails or takes too long, it's recorded as missing and the others still count.
4. A final call combines the summaries into a comparison table and three opportunities, and points out where the summaries disagree.

Code example

Runnable Python using the official SDK's AsyncAnthropic client and Python's built-in asyncio. It needs pip install anthropic, the ANTHROPIC_API_KEY environment variable on your computer or server, and a competitor_notes.txt file.

# parallel_research.py: research three competitors at the same time, then combine.
import asyncio
import pathlib
import anthropic

client = anthropic.AsyncAnthropic()   # async client: many calls can wait at the same time
MODEL = "claude-opus-5-5"
COMPETITORS = ["Acme Scooters", "Bolt Rides", "CityGlide"]
limit = asyncio.Semaphore(3)          # at most 3 calls at once (protects cost and rate limits)

def text_of(response) -> str:
    return "".join(b.text for b in response.content if b.type == "text")

async def research(company: str, notes: str) -> str:
    """One independent task: summarise one competitor."""
    async with limit:
        response = await client.messages.create(
            model=MODEL,
            max_tokens=16000,
            messages=[{"role": "user", "content":
                f"Using only the notes below, summarise {company}'s pricing, strengths and "
                f"weaknesses in 5 bullet points.\n\n<notes>\n{notes}\n</notes>"}],
        )
        return text_of(response)

async def safe_research(company: str, notes: str, seconds: float = 120):
    """Add a timeout, so one slow or failed task can't sink the others."""
    try:
        return company, await asyncio.wait_for(research(company, notes), timeout=seconds)
    except Exception as err:          # a timeout or an API error
        print(f"[warning] {company} failed: {type(err).__name__}")
        return company, None

async def main():
    notes = pathlib.Path("competitor_notes.txt").read_text()

    # Fan-out: start every task now; gather waits until all are finished.
    results = await asyncio.gather(*(safe_research(c, notes) for c in COMPETITORS))

    # Fan-in: keep successes, remember failures.
    found = {company: summary for company, summary in results if summary}
    missing = [company for company, summary in results if not summary]
    if not found:
        raise RuntimeError("Every research task failed. Nothing to combine.")

    combined = "\n\n".join(f"## {c}\n{s}" for c, s in found.items())
    final = await client.messages.create(
        model=MODEL,
        max_tokens=16000,
        messages=[{"role": "user", "content":
            "Compare these competitor summaries in a short table, then list 3 opportunities for us. "
            "If two summaries contradict each other, say so instead of picking one.\n\n" + combined}],
    )
    print(text_of(final))
    if missing:
        print("\nNote: no data for " + ", ".join(missing))

if __name__ == "__main__":
    asyncio.run(main())

Expected output (wording varies):

| Company       | Price      | Strength          | Weakness          |
|---------------|------------|-------------------|-------------------|
| Acme Scooters | $0.30/min  | Large fleet       | Poor app ratings  |
| Bolt Rides    | $0.25/min  | Cheapest          | Few cities        |
| CityGlide     | Subscription | Loyal users     | Slow expansion    |

Opportunities: 1) A better app experience ...

Step-by-step explanation

1. anthropic.AsyncAnthropic() is the SDK's async client. With await, the program can wait for several replies at the same time instead of one by one.
2. asyncio.Semaphore(3) is a "max 3 at once" counter. With 50 competitors, it would stop you sending 50 requests at once and hitting rate limits or a surprise bill.
3. research() is one independent task. It doesn't know about the other competitors.
4. safe_research() adds a timeout with asyncio.wait_for and catches errors, returning None instead of crashing everything.
5. asyncio.gather(...) is the fan-out: it starts every task and waits until all are done.
6. The found and missing lines are the fan-in: sort the results into successes and failures.
7. The final call is the aggregator. It is told to point out contradictions rather than hide them.
8. The program prints which competitors are missing, so the reader knows the report is incomplete.

Collecting and combining results

• Keep results labelled (company → summary) so nothing gets mixed up. gather returns results in the same order as the tasks.
• Use the same format for every task, such as the same bullet structure or the same JSON fields, so results are easy to compare.
• Combine with code when you can, for example adding up numbers or merging lists. Use Claude to combine only when judgement or writing is needed.

Managing timeouts, failures, costs and conflicts

Use cases: when it helps, and when tasks must stay sequential

Advantages and limitations

Best practices

• Double-check that tasks are truly independent before running them in parallel.
• Set a concurrency limit and a timeout for every task.
• Use the same output format for every task.
• Always report which tasks failed or are missing.
• Ask the aggregator to show disagreements instead of hiding them.
• When Claude requests several tool calls in one response, run them together and send all the results back in a single message.

Knowledge check

Mini project

Key takeaways

• Parallel workflows run independent tasks at the same time, then combine them.
• They save time, not money, so limit concurrency.
• Every task needs a timeout and its own error handling. Report anything that's missing.
• Ask the aggregator to show conflicts, and use voting when you need extra confidence.
• If a task needs another's result, keep it sequential.

Further learning

• Building effective agents, the "Parallelization" section (Anthropic engineering blog)
• How to implement tool use, including parallel tool use (official docs)
• Rate limits (official docs)
• Anthropic Python SDK, including the async client (official GitHub repository)