/agentsop-query-routing

name: agentsop-query-routing
version: 0.1.0
description: >-
  Enhancement-overlay SOP for query-type routing — sending a query to the right index / tool
  / engine *before* retrieving, not after. Activate when a calling agent owns a retrieval or
  answering surface that fronts more than one handler (a summary index, a vector index, a
  text-to-SQL engine, a tool) and the inbound queries differ in kind: "summarize this doc"
  vs "find the clause about X" vs "how many orders shipped in Q3". Encodes the one non-
  negotiable insight — **one retriever cannot serve all query types; route first, retrieve
  second** — plus the three router families (LLM/selector, embedding/semantic,
  keyword/rule), confidence-threshold + fallback discipline, and the cross-framework mapping
  (LlamaIndex `RouterQueryEngine` / `SelectorPromptTemplate`, Dify Question Classifier node,
  LangGraph conditional edges). This is an ENHANCE overlay over the per-framework skills —
  cross-link `[[llamaindex]]`, `[[agentsop-dify]]`, `[[agentsop-langgraph]]` for the deep
  API. Search keywords: route query, semantic router, query classification,
  RouterQueryEngine, multi-index routing, pick the right tool for a query.trigger_keywords:
  - "query routing"
  - "route to index"
  - "RouterQueryEngine"
  - "question classifier"
  - "conditional edge router"
  - "text-to-SQL or RAG"
  - "summary vs lookup query"
  - "selector"
  - "intent routing"
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 a