/agentsop-query-routing

name: agentsop-query-routing
version: 0.1.0
description: >-
  Routes heterogeneous queries to the appropriate index, tool, or answering
  engine before retrieval. Use when one endpoint serves multiple handlers,
  such as summary, vector retrieval, text-to-SQL, or tools, and query types
  require different paths. Covers LLM, semantic, and rule-based routers,
  confidence thresholds, fallbacks, and framework mappings. Do not use when
  one handler serves all queries or branching is fixed.
when_to_use:
  - "a single answering endpoint fronts >=2 retrieval/answer handlers (summary index, vector index, SQL engine, tool) and queries differ in kind"
  - "users send a mix of lookup ('what is X'), summarize ('digest doc Y'), and compute ('how many Z') queries to one entry point"
  - "a monolithic VectorStoreIndex is being asked to also answer summary or aggregate queries and quality is uneven"
  - "designing the top-level shape of a RAG / agent system and deciding between one index vs a router over per-type engines"
  - "PR review of a router/classifier/conditional-edge that picks a downstream handler from the query"
when_not_to_use:
  - "exactly one index/tool can correctly serve every query — routing is dead weight"
  - "the split is by tenant/permission, not by query kind — that is multi-tenant filtering, use [[agentsop-multi-tenant-rag]]"
  - "the branch is a fixed deterministic step (always A then B) with no query-dependent choice — that is a static edge, not a router"

Query-Type Routing · Enhancement Overlay

> Third-person operating model for a coder agent that owns a multi-handler > answering surface. Audience is the LLM agent writing/reviewing the routing > code — not the end user.

> **One sentence**: *A retriever is shaped by the query type it was built for; > a summary index, a vector index, and a text-to-SQL engine are not > interchangeable — so classify the query and route first, then retrieve.*

This is an **ENHANCE overlay**. It distills the cross-framework *routing pattern* from three source skills. For the per-framework API, cross-link the base skill: `[[llamaindex]]` (`RouterQueryEngine`), `[[agentsop-dify]]` (Question Classifier node), `[[agentsop-langgraph]]` (conditional edges).

---

1. 何时激活 (Activation Rules)

Activate when **any** of the following holds:

1. The system has **multiple indices / tools / engines** behind one entry point, and a query must be dispatched to exactly one (or a few) of them. 2. Inbound queries **differ in kind** — at least two of: *lookup* ("what does the contract say about termination"), *summarize* ("give me the gist of doc Y"), *compute/aggregate* ("how many tickets closed last week"), *compare* ("diff the 2024 vs 2025 policy"). 3. A `VectorStoreIndex` (or any single retriever) is being stretched to answer query types it was not built for, and quality is uneven across the mix. 4. The user names a routing primitive: `RouterQueryEngine`, `SelectorPromptTemplate`, `LLMSingleSelector`, Dify *Question Classifier*, LangGraph `add_conditional_edges`, "intent classifier", "text-to-SQL or RAG". 5. PR review touches a function that reads a query and returns *which handler* to call.

Do **not** activate when:

• One index/tool serves every query correctly — routing adds an LLM hop and a

failure mode for no benefit (see §6 anti-pattern A1).

• The split is by **who is asking** (tenant / ACL), not **what is asked** — that

is filtering, route to `[[agentsop-multi-tenant-rag]]`.

• The downstream choice is **fixed** (always retrieve then summarize) — that is

a static edge / linear pipeline, not a router.

---

2. 核心心智模型 (Core Mental Model)

Three principles. Violating any of them produces a router that misroutes silently or routes when it should not.

Principle 1 — One retriever cannot serve all query types

The index taxonomy is not cosmetic. From `[[llamaindex]]`: a `SummaryIndex` is a "small, fan-out synthesis" primitive — it reads *every* node to digest a doc; a `VectorStoreIndex` is top-k semantic lookup — it reads the *few* most similar chunks; a text-to-SQL engine answers *aggregate/compute* queries that no chunk contains the answer to. Ask a vector index to "summarize the whole document" and it returns 4 arbitrary chunks; ask a summary index "what is the late-fee clause" and it fans out over the whole corpus wastefully. **The query type names the correct primitive.** Routing is the act of recovering that name at runtime.

> Operational corollary: `index.as_query_engine()` over a single > `VectorStoreIndex` answering a heterogeneous query mix is the symptom this > skill exists to fix. The fix is per-type handlers + a router on top.

Principle 2 — Route first, retrieve second

Routing is a **classification** step that runs *before* any retrieval. It reads only the query (and optionally light context) and emits a *destination*, not an answer. This ordering is what bounds latency and cost: you pay for the router once, then exactly one downstream handler, instead of fanning out to all of them and merging. LlamaIndex's `RouterQueryEngine`, Dify's Question Classifier node feeding IF/ELSE branches, and LangGraph's conditional edge over `state` are the *same shape* — a selector function `(query) -> handler_id` evaluated up front. The three frameworks differ only in *how* the selector is implemented (§7).

Principle 3 — A router is only as good as its destinations' descriptions

Every router — LLM, embedding, or keyword — picks among destinations described in words or examples. In LlamaIndex the signal is the `QueryEngineTool.description`; in Dify it is the class label + instruction; in LangGraph it is whatever the routing function reads off state plus the node names. From `[[llamaindex]]` Dilemma 3: *"invest in `QueryEngineTool.description` — it's the only signal the router/agent sees."* A misroute is, four times out of five, a **bad description**, not a bad model. Fix the description before swapping the