Add to Cursor Add to Claude Copy for LLM View as MD

Parallelization

Parallelization spawns multiple independent tasks at the same time and aggregates results before continuing. Inside an agent loop, this typically means running several tool calls concurrently when they don’t depend on each other. At a system level, it can mean running the same input through multiple evaluators and picking the best (or majority) result.

Hatchet distributes child runs across all running workers where the task is registered. The parent’s slot is freed while children execute, so you don’t hold resources during parallel work.

There are two common variants:

Sectioning: different tasks handle different concerns in parallel (e.g., content generation + safety check).
Voting: the same task runs N times and results are aggregated by majority vote or best score.

When to use

Scenario	Fit
Agent calls 3 independent APIs (weather, news, stock)	Good: no dependencies between calls, latency drops to max of the three
Content generation + safety guardrail in parallel	Good: sectioning, both run at once, block if unsafe
Multiple evaluators vote on content quality	Good: voting, aggregate for more reliable decisions
Processing a batch of items (100+ documents)	Good: see Batch Processing for large-scale fanout
Steps depend on each other (output of A feeds B)	Skip: run sequentially
Provider rate limits are tight	Careful: parallel calls may hit limits; use Rate Limits

How it maps to Hatchet

The parent task spawns children via child spawning. Each child runs on any available worker. The parent’s slot is evicted while children execute, so you’re not holding resources during the parallel work. When all children complete, the parent resumes and aggregates.

Step-by-step walkthrough

Define the parallel tasks

Create separate tasks for each concern. These run independently and can be composed in different patterns.

examples/python/guides/parallelization/worker.py

@content_wf.task()
async def generate_content(input: dict, ctx: Context) -> dict:
    return {"content": mock_generate_content(input["message"])}


@safety_wf.task()
async def safety_check(input: dict, ctx: Context) -> dict:
    return mock_safety_check(input["message"])


@evaluator_wf.task()
async def evaluate_content(input: dict, ctx: Context) -> dict:
    return mock_evaluate(input["content"])

examples/typescript/guides/parallelization/workflow.ts

const contentTask = hatchet.task({
  name: 'generate-content',
  fn: async (input: MessageInput) => {
    return { content: mockGenerateContent(input.message) };
  },
});

const safetyTask = hatchet.task({
  name: 'safety-check',
  fn: async (input: MessageInput) => {
    return mockSafetyCheck(input.message);
  },
});

const evaluateTask = hatchet.task({
  name: 'evaluate-content',
  fn: async (input: { content: string }) => {
    return mockEvaluate(input.content);
  },
});

examples/go/guides/parallelization/main.go

contentTask := client.NewStandaloneTask("generate-content", func(ctx hatchet.Context, input MessageInput) (map[string]interface{}, error) {
	return map[string]interface{}{"content": MockGenerateContent(input.Message)}, nil
})

safetyTask := client.NewStandaloneTask("safety-check", func(ctx hatchet.Context, input MessageInput) (map[string]interface{}, error) {
	result := MockSafetyCheck(input.Message)
	return map[string]interface{}{"safe": result.Safe, "reason": result.Reason}, nil
})

evaluateTask := client.NewStandaloneTask("evaluate-content", func(ctx hatchet.Context, input ContentInput) (map[string]interface{}, error) {
	result := MockEvaluateContent(input.Content)
	return map[string]interface{}{"score": result.Score, "approved": result.Approved}, nil
})

The Ruby SDK is in early access, and may change. We'd love your feedback!

examples/ruby/guides/parallelization/worker.rb

CONTENT_WF.task(:generate_content) do |input, _ctx|
  { 'content' => mock_generate_content(input['message']) }
end

SAFETY_WF.task(:safety_check) do |input, _ctx|
  mock_safety_check(input['message'])
end

EVALUATOR_WF.task(:evaluate_content) do |input, _ctx|
  mock_evaluate_content(input['content'])
end

Sectioning (parallel concerns)

Sectioning runs different concerns in parallel. The example generates content and checks safety at the same time. If the safety check fails, the content is blocked even though generation succeeded.

examples/python/guides/parallelization/worker.py

@hatchet.durable_task(name="ParallelSectioning", execution_timeout="2m")
async def sectioning_task(input: EmptyModel, ctx: DurableContext) -> dict:
    content_result, safety_result = await asyncio.gather(
        content_wf.aio_run(input={"message": input["message"]}),
        safety_wf.aio_run(input={"message": input["message"]}),
    )

    if not safety_result["safe"]:
        return {"blocked": True, "reason": safety_result["reason"]}
    return {"blocked": False, "content": content_result["content"]}

Voting (parallel consensus)

Voting runs the same evaluation N times and aggregates by majority or average score. This produces more reliable decisions than a single evaluation.

examples/python/guides/parallelization/worker.py

@hatchet.durable_task(name="ParallelVoting", execution_timeout="3m")
async def voting_task(input: EmptyModel, ctx: DurableContext) -> dict:
    votes = await asyncio.gather(
        evaluator_wf.aio_run(input={"content": input["content"]}),
        evaluator_wf.aio_run(input={"content": input["content"]}),
        evaluator_wf.aio_run(input={"content": input["content"]}),
    )

    approvals = sum(1 for v in votes if v["approved"])
    avg_score = sum(v["score"] for v in votes) / len(votes)

    return {"approved": approvals >= 2, "average_score": avg_score, "votes": len(votes)}

Run the worker

examples/python/guides/parallelization/worker.py

worker = hatchet.worker(
    "parallelization-worker",
    workflows=[content_wf, safety_wf, evaluator_wf, sectioning_task, voting_task],
    slots=10,
)
worker.start()

For large-scale parallelism (hundreds or thousands of items), see the Batch Processing guide, which covers fan-out with concurrency control.

Large-scale fan-out with concurrency limits and progress tracking.

Batch Processing

Parallelization applies within one iteration of an agent loop when multiple tools are independent.

Reasoning Loop

Combine voting (parallel evaluators) with optimization (feedback loop) for higher-quality iteration.

Evaluator-Optimizer

The Hatchet concept: spawn children in parallel, parent waits for all.

Fanout