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

Routing

Routing classifies an incoming request and directs it to a specialist durable task. A single entry point handles all requests; the routing logic (an LLM call, a rule-based check, or a keyword match) determines which downstream task runs. Only one branch executes per request.

This pattern improves response quality because each specialist task has its own prompt, tools, and context optimized for that category. It also simplifies the caller: trigger one task and let the router decide where to send it.

When to use

Scenario	Fit
Customer service (support vs. sales vs. billing)	Good: distinct domains with different prompts and tools
Document processing (invoice vs. receipt vs. contract)	Good: each type needs different extraction logic
Request triage (simple auto-reply vs. complex agent)	Good: avoid expensive agent loops for easy questions
All requests follow the same path	Skip: no benefit from routing
Routing rules are simple and known at definition time	Use Parent Conditions in a DAG instead

How it maps to Hatchet

The router is a durable task. It spawns a classifier child task (or does classification inline), then spawns the matching specialist as a child run. Since each specialist is a separate durable task, they can have their own timeouts, retries, rate limits, and concurrency settings.

Routing decisions are checkpointed. If the worker dies after classification but before the specialist finishes, the router resumes and does not re-classify.

Step-by-step walkthrough

Define the classifier task

A separate task classifies the incoming message. This lets you observe the classification result and retry independently if the LLM fails.

examples/python/guides/routing/worker.py

@hatchet.durable_task(name="ClassifyMessage")
async def classify_message(input: EmptyModel, ctx: DurableContext) -> dict:
    return {"category": mock_classify(input["message"])}

examples/typescript/guides/routing/workflow.ts

const classifyTask = hatchet.durableTask({
  name: 'classify-message',
  fn: async (input: MessageInput) => {
    return { category: mockClassify(input.message) };
  },
});

examples/go/guides/routing/main.go

classifyTask := client.NewStandaloneDurableTask("classify-message", func(ctx hatchet.DurableContext, input MessageInput) (map[string]interface{}, error) {
	return map[string]interface{}{"category": MockClassify(input.Message)}, nil
})

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

examples/ruby/guides/routing/worker.rb

CLASSIFY_TASK = HATCHET.durable_task(name: 'ClassifyMessage') do |input, _ctx|
  { 'category' => mock_classify(input['message']) }
end

Define the specialist tasks

Each specialist is a standalone durable task with its own prompt and tools. They run independently with their own timeout and retry settings.

examples/python/guides/routing/worker.py

@hatchet.durable_task(name="HandleSupport")
async def handle_support(input: EmptyModel, ctx: DurableContext) -> dict:
    return {"response": mock_reply(input["message"], "support"), "category": "support"}


@hatchet.durable_task(name="HandleSales")
async def handle_sales(input: EmptyModel, ctx: DurableContext) -> dict:
    return {"response": mock_reply(input["message"], "sales"), "category": "sales"}


@hatchet.durable_task(name="HandleDefault")
async def handle_default(input: EmptyModel, ctx: DurableContext) -> dict:
    return {"response": mock_reply(input["message"], "other"), "category": "other"}

Route with a durable task

The router classifies the message, then spawns the matching specialist. The classification result is checkpointed, so if the worker dies after classifying, it resumes and spawns the specialist without re-classifying.

examples/python/guides/routing/worker.py

@hatchet.durable_task(name="MessageRouter", execution_timeout="2m")
async def message_router(input: EmptyModel, ctx: DurableContext) -> dict:
    classification = await classify_message.aio_run({"message": input["message"]})

    if classification["category"] == "support":
        return await handle_support.aio_run({"message": input["message"]})
    if classification["category"] == "sales":
        return await handle_sales.aio_run({"message": input["message"]})
    return await handle_default.aio_run({"message": input["message"]})

Run the worker

examples/python/guides/routing/worker.py

worker = hatchet.worker(
    "routing-worker",
    workflows=[classify_message, handle_support, handle_sales, handle_default, message_router],
    slots=5,
)
worker.start()

For simple routing based on input fields (not LLM classification), you can skip the classify task and route directly in the durable task body based on input.type or similar fields.

Routing vs. DAG branching

	Routing (durable task)	DAG Parent Conditions
Branch decided by	Runtime code (`if`/`else`, LLM call)	Declared conditions on parent task output
Use when	Category is unknown until an LLM classifies it	Branch criteria are known at workflow definition time
Observability	Router + specialist appear as separate runs	All branches visible in the DAG graph