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

Multi-Agent

Multi-agent orchestration uses a coordinating agent that delegates work to specialist agents. Unlike routing (which classifies once and calls one handler), the orchestrator runs a reasoning loop: it may call multiple specialists across multiple iterations, passing results between them, until the overall goal is met.

Each specialist is a separate durable task with its own prompt, tools, timeout, and retry settings. The orchestrator’s LLM decides which specialist to call next based on the accumulated context.

When to use

Scenario	Fit
Complex tasks needing different expertise (research + code + writing)	Good: each specialist focuses on one domain
Customer service with support, sales, and billing specialists	Good: orchestrator picks the right expert per turn
Tasks where output from one specialist feeds the next	Good: orchestrator passes context between calls
Simple tasks a single agent can handle end-to-end	Skip: orchestration overhead isn’t worth it
Specialists always run in a fixed sequence	Use LLM Pipelines instead

How it maps to Hatchet

The orchestrator is a durable task running a reasoning loop via child spawning. Each specialist is a standalone durable task spawned as a child run. The orchestrator’s LLM returns structured tool calls, and each tool name maps to a specialist task.

Because each specialist call is a child run, the orchestrator’s slot is freed while specialists execute. If the orchestrator dies mid-loop, it resumes from the last checkpoint without re-running completed specialist calls.

Step-by-step walkthrough

Define the specialist tasks

Each specialist is a standalone durable task with its own prompt and timeout. They run independently and can be reused across different orchestrators.

examples/python/guides/multi_agent/worker.py

@hatchet.durable_task(name="ResearchSpecialist", execution_timeout="3m")
async def research(input: EmptyModel, ctx: DurableContext) -> dict:
    return {"result": mock_specialist_llm(input["task"], "research")}


@hatchet.durable_task(name="WritingSpecialist", execution_timeout="2m")
async def write(input: EmptyModel, ctx: DurableContext) -> dict:
    return {"result": mock_specialist_llm(input["task"], "writing")}


@hatchet.durable_task(name="CodeSpecialist", execution_timeout="2m")
async def code(input: EmptyModel, ctx: DurableContext) -> dict:
    return {"result": mock_specialist_llm(input["task"], "code")}

examples/typescript/guides/multi-agent/workflow.ts

const researchTask = hatchet.durableTask({
  name: 'research-specialist',
  executionTimeout: '3m',
  fn: async (input: SpecialistInput) => {
    return { result: mockSpecialistLlm(input.task, 'research') };
  },
});

const writingTask = hatchet.durableTask({
  name: 'writing-specialist',
  executionTimeout: '2m',
  fn: async (input: SpecialistInput) => {
    return { result: mockSpecialistLlm(input.task, 'writing') };
  },
});

const codeTask = hatchet.durableTask({
  name: 'code-specialist',
  executionTimeout: '2m',
  fn: async (input: SpecialistInput) => {
    return { result: mockSpecialistLlm(input.task, 'code') };
  },
});

examples/go/guides/multi-agent/main.go

researchTask := client.NewStandaloneDurableTask("research-specialist", func(ctx hatchet.DurableContext, input SpecialistInput) (map[string]interface{}, error) {
	return map[string]interface{}{"result": MockSpecialistLLM(input.Task, "research")}, nil
})

writingTask := client.NewStandaloneDurableTask("writing-specialist", func(ctx hatchet.DurableContext, input SpecialistInput) (map[string]interface{}, error) {
	return map[string]interface{}{"result": MockSpecialistLLM(input.Task, "writing")}, nil
})

codeTask := client.NewStandaloneDurableTask("code-specialist", func(ctx hatchet.DurableContext, input SpecialistInput) (map[string]interface{}, error) {
	return map[string]interface{}{"result": MockSpecialistLLM(input.Task, "code")}, nil
})

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

examples/ruby/guides/multi_agent/worker.rb

RESEARCH_TASK = HATCHET.durable_task(name: 'ResearchSpecialist', execution_timeout: '3m') do |input, _ctx|
  { 'result' => mock_specialist_llm(input['task'], 'research') }
end

WRITING_TASK = HATCHET.durable_task(name: 'WritingSpecialist', execution_timeout: '2m') do |input, _ctx|
  { 'result' => mock_specialist_llm(input['task'], 'writing') }
end

CODE_TASK = HATCHET.durable_task(name: 'CodeSpecialist', execution_timeout: '2m') do |input, _ctx|
  { 'result' => mock_specialist_llm(input['task'], 'code') }
end

Orchestrator loop

The orchestrator runs a reasoning loop: call LLM, parse tool choice, spawn specialist, observe result, repeat. Context accumulates across iterations so later specialist calls have full history.

examples/python/guides/multi_agent/worker.py

@hatchet.durable_task(name="MultiAgentOrchestrator", execution_timeout="15m")
async def orchestrator(input: EmptyModel, ctx: DurableContext) -> dict:
    messages = [{"role": "user", "content": input["goal"]}]

    for _ in range(10):
        response = mock_orchestrator_llm(messages)

        if response["done"]:
            return {"result": response["content"]}

        specialist = specialists.get(response["tool_call"]["name"])
        if not specialist:
            raise ValueError(f"Unknown specialist: {response['tool_call']['name']}")

        result = await specialist.aio_run(input={
            "task": response["tool_call"]["args"]["task"],
            "context": "\n".join(m["content"] for m in messages),
        })

        messages.append({"role": "assistant", "content": f"Called {response['tool_call']['name']}"})
        messages.append({"role": "tool", "content": result["result"]})

    return {"result": "Max iterations reached"}

Run the worker

examples/python/guides/multi_agent/worker.py

worker = hatchet.worker(
    "multi-agent-worker",
    workflows=[research, write, code, orchestrator],
    slots=10,
)
worker.start()

⚠️

Always set a max iteration count and execution timeout on the orchestrator. Without bounds, the loop can call specialists indefinitely.

Multi-agent vs. routing

	Multi-agent	Routing
Specialist calls	Multiple, across loop iterations	One per request
Orchestration	Reasoning loop, LLM decides next step dynamically	Classify once, route once
Use when	Task needs multiple types of expertise	Task fits a single specialist

Multi-agent is a reasoning loop where “tools” are specialist durable tasks instead of API calls.

Reasoning Loop

Classify once and route to one handler. Multi-agent loops and may call many.

Routing

When multiple specialists can work independently, spawn them in parallel within a single iteration.

Parallelization

The Hatchet primitive used to spawn specialist tasks from the orchestrator.

Child Spawning

Next Steps

Durable Task Execution: understand checkpointing and replay for the orchestrator
Child Spawning: spawn specialist tasks from the orchestrator loop
Timeouts: set execution timeouts on the orchestrator and each specialist
Concurrency Control: limit how many orchestrator runs execute in parallel

Routing Parallelization

We use cookies

Multi-Agent

When to use

How it maps to Hatchet

Step-by-step walkthrough

Define the specialist tasks

Orchestrator loop

Run the worker

Multi-agent vs. routing

Related Patterns

Next Steps