Haystack Tutorial (Python): building conditional routing for beginners

This tutorial shows you how to build a simple conditional router in Haystack so your pipeline can send different inputs to different branches based on a rule. You need this when one query should trigger one path, but another query should go somewhere else, like routing urgent support tickets differently from normal ones.

What You'll Need

• •Python 3.10+
• •haystack-ai installed
• •A working internet connection if you want to use an online generator later
• •No API key is required for this routing example
• •Basic familiarity with Haystack Pipeline, components, and run()

Step-by-Step

1. •Start with the core idea: a router takes one input and emits one of several outputs depending on a condition. In Haystack, the cleanest beginner-friendly way is to use ConditionalRouter from the core components package.

from haystack import Pipeline
from haystack.components.routers import ConditionalRouter

router = ConditionalRouter(
    routes=[
        {
            "condition": "{{ 'urgent' in text.lower() }}",
            "output": "{{ text }}",
            "output_name": "urgent_text",
            "output_type": str,
        },
        {
            "condition": "{{ True }}",
            "output": "{{ text }}",
            "output_name": "normal_text",
            "output_type": str,
        },
    ]
)

2. •Add downstream components that will handle each branch. For beginners, PromptBuilder is useful because it makes the branching visible without needing a full LLM setup yet.

from haystack.components.builders import PromptBuilder

urgent_builder = PromptBuilder(
    template="URGENT PATH: Escalate this message immediately:\n{{ text }}"
)

normal_builder = PromptBuilder(
    template="NORMAL PATH: Handle this message in the standard queue:\n{{ text }}"
)

3. •Wire the router and builders into a pipeline. The important part is that each route output name becomes the input name for the next component, so keep them aligned.

pipeline = Pipeline()

pipeline.add_component("router", router)
pipeline.add_component("urgent_builder", urgent_builder)
pipeline.add_component("normal_builder", normal_builder)

pipeline.connect("router.urgent_text", "urgent_builder.text")
pipeline.connect("router.normal_text", "normal_builder.text")

4. •Run the pipeline with an urgent message first, then inspect which branch produced output. The router will only activate the matching path, which makes it easy to split logic without writing manual if/else code around the pipeline.

result = pipeline.run(
    data={
        "router": {
            "text": "This is urgent: customer account locked after fraud alert"
        }
    }
)

print(result["urgent_builder"]["prompt"])

5. •Test the normal path with a message that does not match your condition. You should see the other builder produce output instead, which confirms the fallback route works as expected.

result = pipeline.run(
    data={
        "router": {
            "text": "Customer wants to update their mailing address"
        }
    }
)

print(result["normal_builder"]["prompt"])

Testing It

Run both examples and confirm that only one downstream component produces output for each input. For the urgent case, check that urgent_builder returns a prompt containing your original text, and for the normal case check normal_builder.

If you get a routing error, it usually means one of two things: your Jinja condition has a syntax issue, or your route names do not match the connected input names. In Haystack routing pipelines, those names must line up exactly.

A good next test is to make your condition stricter, such as checking for multiple keywords or using structured fields instead of raw text. That is how you move from demo routing to production-grade orchestration.

Next Steps

• •Replace PromptBuilder with real processors like an LLM generator or a document retriever.
• •Learn how to route on structured metadata instead of plain text.
• •Add more than two branches and build a default/fallback route for unsupported inputs.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.