Interface QueryRouterConfig

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,
});
interface QueryRouterConfig {
    knowledgeCorpus: string[];
    confidenceThreshold?: number;
    classifierModel?: string;
    classifierProvider?: string;
    maxTier?: QueryTier;
    embeddingProvider?: string;
    embeddingModel?: string;
    generationModel?: string;
    generationModelDeep?: string;
    generationProvider?: string;
    graphEnabled?: boolean;
    deepResearchEnabled?: boolean;
    conversationWindowSize?: number;
    maxContextTokens?: number;
    cacheResults?: boolean;
    availableTools?: string[];
    graphExpand?: ((seedChunks) => Promise<RetrievedChunk[]>);
    rerank?: ((query, chunks, topN) => Promise<RetrievedChunk[]>);
    verifyCitations?: boolean;
    deepResearch?: ((query, sources) => Promise<{
        synthesis: string;
        sources: RetrievedChunk[];
    }>);
    onClassification?: ((result) => void);
    onRetrieval?: ((result) => void);
    apiKey?: string;
    baseUrl?: string;
    embeddingApiKey?: string;
    embeddingBaseUrl?: string;
    githubRepos?: RepoIndexConfig;
    strategyConfig?: QueryRouterStrategyConfig;
    includePlatformKnowledge?: boolean;
}

Properties

knowledgeCorpus confidenceThreshold? classifierModel? classifierProvider? maxTier? embeddingProvider? embeddingModel? generationModel? generationModelDeep? generationProvider? graphEnabled? deepResearchEnabled? conversationWindowSize? maxContextTokens? cacheResults? availableTools? graphExpand? rerank? verifyCitations? deepResearch? onClassification? onRetrieval? apiKey? baseUrl? embeddingApiKey? embeddingBaseUrl? githubRepos? strategyConfig? includePlatformKnowledge?

Properties

knowledgeCorpus

knowledgeCorpus: string[]

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.

Optional confidenceThreshold

confidenceThreshold?: number

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

Default

0.7

Optional classifierModel

classifierModel?: string

LLM model for the classifier.

Default

'gpt-4o-mini'

Optional classifierProvider

classifierProvider?: string

LLM provider for the classifier.

Default

'openai'

Optional maxTier

maxTier?: QueryTier

Maximum tier the classifier may assign.

Default

3

Optional embeddingProvider

embeddingProvider?: string

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. A provider other than OpenAI that has a key variable of its own embeds with that key alone (see embeddingApiKey).

Default

'openai'

Optional embeddingModel

embeddingModel?: string

Embedding model identifier.

Default

'text-embedding-3-small'

Optional generationModel

generationModel?: string

LLM model for T0/T1 generation.

Default

'gpt-4o-mini'

Optional generationModelDeep

generationModelDeep?: string

LLM model for T2/T3 generation (deep).

Default

'gpt-4o'

Optional generationProvider

generationProvider?: string

LLM provider for generation.

Default

'openai'

Optional graphEnabled

graphEnabled?: boolean

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

Default

true

Optional deepResearchEnabled

deepResearchEnabled?: boolean

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

Default

true

Optional conversationWindowSize

conversationWindowSize?: number

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

Default

5

Optional maxContextTokens

maxContextTokens?: number

Maximum estimated tokens to allocate for documentation context.

Default

4000

Optional cacheResults

cacheResults?: boolean

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

Optional availableTools

availableTools?: string[]

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

Default

[]

Optional graphExpand

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

Optional host-provided graph expansion callback.

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

Type declaration

Optional rerank

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

Optional host-provided reranker callback.

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

Type declaration

Optional verifyCitations

verifyCitations?: boolean

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.

Optional deepResearch

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

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.

Type declaration

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

    • Parameters

      • query: string
      • sources: string[]

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

Optional onClassification

onClassification?: ((result) => void)

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

Type declaration

Optional onRetrieval

onRetrieval?: ((result) => void)

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

Type declaration

Optional apiKey

apiKey?: string

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 prefers OPENAI_API_KEY and falls back to OPENROUTER_API_KEY with the OpenRouter compatibility base URL.

Optional baseUrl

baseUrl?: string

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.

Optional embeddingApiKey

embeddingApiKey?: string

Optional API key override for embeddings only.

When omitted, embeddings fall back to apiKey when they use the classifier's or the generator's provider, and never take it for another vendor's. Without that, 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, so another vendor's key never reaches it; an OpenAI one, or one without a key variable such as Ollama, takes the first provider key set, OPENAI_API_KEY first and OPENROUTER_API_KEY last. This is useful when generation uses an OpenAI-compatible endpoint like OpenRouter but embeddings should stay on a direct OpenAI key.

Optional embeddingBaseUrl

embeddingBaseUrl?: string

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.

Optional githubRepos

githubRepos?: RepoIndexConfig

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.

Optional strategyConfig

strategyConfig?: QueryRouterStrategyConfig

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

Optional includePlatformKnowledge

includePlatformKnowledge?: boolean

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

Settings

Member Visibility

Theme

On This Page

knowledgeCorpusconfidenceThresholdclassifierModelclassifierProvidermaxTierembeddingProviderembeddingModelgenerationModelgenerationModelDeepgenerationProvidergraphEnableddeepResearchEnabledconversationWindowSizemaxContextTokenscacheResultsavailableToolsgraphExpandrerankverifyCitationsdeepResearchonClassificationonRetrievalapiKeybaseUrlembeddingApiKeyembeddingBaseUrlgithubReposstrategyConfigincludePlatformKnowledge