Skip to main content

Interface: QueryRouterConfig

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:427

Public constructor configuration for the QueryRouter pipeline.

knowledgeCorpus is required. All other fields are optional and default to the values in DEFAULT_QUERY_ROUTER_CONFIG.

Example​

const router = new QueryRouter({
knowledgeCorpus: ['./docs', './packages/agentos/docs'],
availableTools: ['web_search', 'deep_research'],
maxTier: 3,
});

Properties​

apiKey?​

optional apiKey: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:589

Optional API key override for classifier and generator LLM calls.

When omitted, a classifier or generator whose provider is not OpenAI takes that provider's own key variable (MINIMAX_API_KEY for minimax), and none when it is unset, so generateText resolves the provider's credentials and no other vendor's key reaches it. An OpenAI one takes OPENAI_API_KEY, else OPENROUTER_API_KEY with the OpenRouter compatibility base URL, else no key: another vendor's key never reaches OpenAI. One that names no provider gets no key from the router, and generateText reads the key of the provider it detects. An empty value counts as omitted.


availableTools?​

optional availableTools: string[]

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:518

Optional tool/capability names exposed to the classifier prompt so it can reason about what the runtime can actually do.

Default​

[]

baseUrl?​

optional baseUrl: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:600

Optional base URL override for classifier and generator LLM providers.

When omitted, QueryRouter auto-selects the OpenRouter compatibility URL only when OPENROUTER_API_KEY is being used implicitly for an OpenAI classifier or generator. Any other provider takes the endpoint generateText resolves for it (MINIMAX_BASE_URL, or MiniMax's default). An empty or whitespace-only value counts as omitted.


cacheResults?​

optional cacheResults: boolean

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:511

Whether to cache query results.

When enabled, route() caches completed QueryResult objects in memory and reuses them for identical query/history/request-option inputs until router state changes (for example corpus refresh or retriever swap).

Default​

true

classifierModel?​

optional classifierModel: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:445

LLM model for the classifier.

Default​

'gpt-4o-mini'

classifierProvider?​

optional classifierProvider: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:448

LLM provider for the classifier.

Default​

'openai'

confidenceThreshold?​

optional confidenceThreshold: number

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:442

Minimum confidence threshold for accepting a classification result. If confidence falls below this, the router may escalate to a higher tier.

Default​

0.7

conversationWindowSize?​

optional conversationWindowSize: number

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:494

Number of recent conversation messages to include as context for classification and generation.

Default​

5

deepResearch()?​

optional deepResearch: (query, sources) => Promise<{ sources: RetrievedChunk[]; synthesis: string; }>

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:559

Optional host-provided deep research callback.

Provide this to replace the built-in placeholder research branch with a real multi-source research runtime. The sources argument receives normalized research-source hints such as web, docs, or media, not raw classifier retrieval labels.

Parameters​

query​

string

sources​

string[]

Returns​

Promise<{ sources: RetrievedChunk[]; synthesis: string; }>


deepResearchEnabled?​

optional deepResearchEnabled: boolean

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:487

Whether to enable deep research mode for tier 3 queries. Research mode performs iterative multi-pass retrieval and synthesis.

Default​

true

embeddingApiKey?​

optional embeddingApiKey: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:620

Optional API key override for embeddings only.

An embedding call carries only a key of the vendor it goes to. When omitted, embeddings fall back to apiKey only when the embedding provider is named and is the classifier's or the generator's provider, and never take it for another vendor's. Without that, an OpenAI embedding provider takes OPENAI_API_KEY, else OPENROUTER_API_KEY (with the OpenRouter compatibility URL), else no key, and vector retrieval stays off (disabled-no-key): ANTHROPIC_API_KEY or another vendor's key is never sent to OpenAI. An embedding provider other than OpenAI that has a key variable of its own takes that key (GEMINI_API_KEY for gemini, MINIMAX_API_KEY for minimax), or none when it is unset. A provider without a key variable, such as Ollama, takes no key and embeds without one when it has a base URL. This is useful when generation uses an OpenAI-compatible endpoint like OpenRouter but embeddings should stay on a direct OpenAI key.


embeddingBaseUrl?​

optional embeddingBaseUrl: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:634

Optional base URL override for embeddings only.

When omitted, embeddings inherit baseUrl when they use the classifier's or the generator's provider, unless embeddingApiKey is explicitly set, in which case the embedding path assumes the provider's default endpoint. An embedding provider other than OpenAI otherwise gets no URL from the router and uses its own endpoint. If neither override is set and QueryRouter falls back to OPENROUTER_API_KEY, it automatically uses the OpenRouter compatibility URL for embeddings as well. An empty or whitespace-only value counts as omitted, here and in an inherited baseUrl.


embeddingModel?​

optional embeddingModel: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:464

Embedding model identifier.

Default​

'text-embedding-3-small'

embeddingProvider?​

optional embeddingProvider: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:461

Embedding provider name. Without one, the router takes the provider of the first provider key set, as for the classifier, except MiniMax: it publishes no embedding model, so a MiniMax key alone leaves embeddings on openai. Each provider embeds with a key of its own vendor alone, or none (see embeddingApiKey).

Default​

'openai'

generationModel?​

optional generationModel: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:467

LLM model for T0/T1 generation.

Default​

'gpt-4o-mini'

generationModelDeep?​

optional generationModelDeep: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:470

LLM model for T2/T3 generation (deep).

Default​

'gpt-4o'

generationProvider?​

optional generationProvider: string

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:473

LLM provider for generation.

Default​

'openai'

githubRepos?​

optional githubRepos: RepoIndexConfig

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:642

Configuration for background GitHub repository indexing.

When provided, the router will asynchronously index GitHub repos after init() completes and merge the resulting chunks into the corpus.


graphEnabled?​

optional graphEnabled: boolean

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:480

Whether to enable GraphRAG-based retrieval for tier >= 2 queries. Requires a configured GraphRAG engine.

Default​

true

graphExpand()?​

optional graphExpand: (seedChunks) => Promise<RetrievedChunk[]>

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:526

Optional host-provided graph expansion callback.

Provide this to replace the built-in placeholder graphExpand() branch with a real GraphRAG or relationship-expansion implementation.

Parameters​

seedChunks​

RetrievedChunk[]

Returns​

Promise<RetrievedChunk[]>


includePlatformKnowledge?​

optional includePlatformKnowledge: boolean

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:663

Load bundled platform knowledge (tools, skills, FAQ, API reference, troubleshooting) into the corpus during init().

When enabled, the router ships with instant knowledge about every AgentOS capability — no external docs required for platform questions.

Default​

true

knowledgeCorpus​

knowledgeCorpus: string[]

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:435

Directories containing .md / .mdx files to ingest as the knowledge corpus.

init() will throw if these paths resolve to zero readable markdown sections, because a successful router init should imply a non-empty corpus.


maxContextTokens?​

optional maxContextTokens: number

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:500

Maximum estimated tokens to allocate for documentation context.

Default​

4000

maxTier?​

optional maxTier: QueryTier

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:451

Maximum tier the classifier may assign.

Default​

3

onClassification()?​

optional onClassification: (result) => void

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:568

Hook called after classification completes. Receives the ClassificationResult for consumer integration.

Parameters​

result​

ClassificationResult

Returns​

void


onRetrieval()?​

optional onRetrieval: (result) => void

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:574

Hook called after retrieval completes. Receives the RetrievalResult for consumer integration.

Parameters​

result​

RetrievalResult

Returns​

void


rerank()?​

optional rerank: (query, chunks, topN) => Promise<RetrievedChunk[]>

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:534

Optional host-provided reranker callback.

Provide this to replace the built-in lexical heuristic reranker with a provider-backed or cross-encoder reranker.

Parameters​

query​

string

chunks​

RetrievedChunk[]

topN​

number

Returns​

Promise<RetrievedChunk[]>


strategyConfig?​

optional strategyConfig: QueryRouterStrategyConfig

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:652

Retrieval strategy configuration for the HyDE-aware query router.

Controls how the classifier selects between none, simple, moderate (HyDE), and complex (HyDE + decompose) retrieval strategies.

See​

QueryRouterStrategyConfig


verifyCitations?​

optional verifyCitations: boolean

Defined in: packages/agentos/src/orchestration/pipeline/query/types.ts:549

Enable post-generation citation verification when the router has an active embedding path and retrieved source chunks.

When enabled, route() runs CitationVerifier over the generated answer and retrieved sources, then attaches the result to QueryResult.grounding. If embeddings are unavailable or no sources were retrieved, verification is skipped gracefully.