Prompt Routing Pattern: Per-Category Handler Bundles for Production AI (2026)

Q: What is the prompt routing pattern?

Prompt routing is the pattern of mapping each classified category to a complete handler bundle — prompt template, allowed tools, guardrail set, model choice, retrieval source, and post-processing rules — and routing each request through the bundle that matches its category. The routing decision is deterministic, table-driven, and auditable: the router itself is a tiny stateless component that does nothing but look up the category in a routing table and execute the matched bundle. Prompt routing is the second half of classification-first architecture (classification produces the routing key, routing acts on it) and the foundation of any production AI system that handles multiple distinct categories of request. It transforms the AI system from a single overloaded prompt-handler into a registry of small, well-scoped, independently-tunable handlers.

Q: Why not just put routing logic inside one big prompt?

A single mega-prompt that tries to handle every case grows to thousands of tokens, contains contradictory instructions, cannot be rolled back per behaviour (changing one rule risks all others), provides no scoping of tool access, and cannot be A/B tested per route. Per-category bundles solve each of these: each handler is small and focused on one category; rollback is per-bundle (a routing-table revert); tools are scoped per bundle (least-privilege principle); A/B tests are run on one route's traffic without affecting others. Prompt routing also gives per-route observability — quality metrics per category instead of aggregate quality that hides per-category degradation. The single-prompt approach works in demos and fails at the long tail of production input distribution.

Q: What does a handler bundle contain?

A handler bundle is a complete recipe for handling one category. It specifies: (1) prompt template with explicit version tag (e.g., "order-status-v3"), (2) list of allowed tools as a whitelist (not a blacklist), (3) guardrail set (which named guardrails to apply), (4) model name and parameters (temperature, max tokens, top-p), (5) retrieval source (none, RAG index name, knowledge graph), (6) post-processing rules (output schema validation, redaction, formatting), and (7) audit-log fields. The bundle is the atomic unit of routing — when adding or modifying a category, the entire bundle is added or modified. Treating bundles as atomic prevents partial-update bugs (e.g., changing the template but forgetting to update the tool list) and makes routing-table changes reviewable in single diffs.

Q: How does prompt routing compose with classification-first and versioned templates?

Three-stage pipeline: classify → route → generate. Classification-first produces the category for every request (the upstream layer); the router maps category to bundle (the middle layer); the versioned template inside the bundle generates the response (the downstream layer). Each stage has a single, narrow responsibility and can be tested, monitored, and evolved independently. Templates are versioned (e.g., "order-status-v3"); the routing table pins each bundle to a specific template version; deploying a new template version is a routing-table update, not a code release; rollback is reverting the routing table. Per-category guardrails are also versioned and shared across bundles where appropriate; the bundle lists which guardrails apply for that category and the runtime applies them. The composition enforces clean separation of concerns and makes the system reasonable about and rollable.

Q: What are the main implementation patterns for the routing table?

Four production patterns. (1) YAML/JSON in version control — most common; routing table is a config file, edits are PRs with reviewable diffs, rollback is reverting; works for up to a few hundred categories with occasional updates. (2) Database-backed registry — for many categories, frequent updates, or per-tenant routing variations; supports admin UI and API-driven changes; trade-off is database operational complexity. (3) Code-based with strong typing — bundles are typed constants in the codebase; catches misconfiguration at compile time; supports IDE autocomplete; trade-off is updates require deploys. (4) Hybrid (recommended) — handler bundles defined in code with strong typing and tests; mapping from category to bundle is a configuration file that can be updated independently. The hybrid separates "what each handler does" (stable, code) from "which category maps to which handler" (operational, config), giving the best of both.

Q: What are the most common prompt routing anti-patterns?

Putting routing logic inside the prompt template ("if user asks X do Y") — defeats the purpose of routing and reproduces single-prompt failures one level deeper. One mega-bundle for many categories — gradual consolidation rebuilds the original problem; resist unless bundles are truly identical. Default route as a silent catch-all — the default is a fail-safe, not a feature; alert when default-route volume exceeds 1-3%; investigate each spike as a taxonomy gap. Tool access via "the model decides what tools it needs" — for routed systems, the bundle's tool list is authoritative; the model should not have access to tools outside its bundle's whitelist; enforce at runtime, not in the prompt. Routing changes that bypass review — treat the routing table as product behaviour with full PR review, automated tests, and gradual rollout, not as low-stakes config that anyone can push directly.