Knowledge search

Agentic retrieval is an feature — it requires the agentic-retrieval license entitlement. When the entitlement is absent, the tool does not appear in the agent editor. See Editions for activation details.

What the pipeline does

When you enable the knowledge search tool on an agent, each user question triggers a multi-phase retrieval pipeline before the model writes its answer. Phase 1 — routing and memory (parallel) A classification step reads the question and decides which knowledge bases to search first and which to hold as fallback sources. Routing rules (configured in the wizard’s Routing step) describe categories of questions in plain language and map them to specific sources; without rules, every enabled knowledge base is searched. At the same time, the pipeline checks the memory context (if one is configured) for relevant prior conversation summaries and curated notes. Identifier pins If vocabulary identifier sets are configured, the pipeline detects product names, standards codes, or other typed identifiers in the question and pins the files that match them. Fuzzy identifier sets use approximate name matching; exact sets require an exact match. Pinned files are boosted in reranking. Phase 2 — search (main and speculative fallback, parallel) For each enabled knowledge base, the pipeline generates query variations and searches. Documents and manuals use Hypothetical Document Embedding (HyDE) — the model drafts a passage that a relevant document might contain, then searches for real passages close to that draft — plus multi-query expansion with Reciprocal Rank Fusion (RRF) to combine results. Conversations and records use keyword-focused search without HyDE. Fallback sources are searched in parallel with main sources and incorporated only when the main results fall below the fallback threshold. Phase 3 — rerank and return Results from all sources are merged, boosted (for pinned items and identifier matches), and re-scored by the configured reranker. The top-K passages are returned to the model.

Enabling and configuring the tool

Open the agent in the workbench and scroll to the Knowledge & memory section. Flip the Knowledge search switch to enable the tool. A seven-step configuration wizard opens automatically:

Step	What you configure
Sources	Which knowledge bases to include; the content kind for each (documents, conversations, or records); per-source retrieval instructions
Routing	Plain-language rules that route specific question types to the right sources
Vocabulary	Glossary terms, identifier sets (product names, codes, standards), query-rewrite rules, and a document style hint
Memory	How memory entries from the memory knowledge base shape retrieval
Behavior	Reranker, result count, fallback threshold, project search, extra instructions, and advanced tuning
Verification	Whether finished answers are checked against their sources, and how — see Answer verification below
Review	Summary of all settings before applying

Click Finish in the wizard and then Save the agent.

Configuration options

All thirteen options are optional. Omitted options fall back to the defaults shown below.

UI label	Config key	Default	What it does	When to change it
Extra instructions (optional)	`instructions`	(empty)	Free-text guidance prepended to the tool description shown to the model; useful for “check this source first” or scope hints.	When the model misuses the tool or needs context about when to call it.
Reranker	`reranker`	`"none"`	Reranker backend used to re-score results after retrieval. `"none"` disables reranking.	Strongly recommended — set a reranker whenever one is available on your deployment; it materially improves result quality.
Managed context	`managed_context`	off	When on, users must preselect items before the tool will search. The tool returns an instruction to the model asking the user to preselect if no items are pinned.	Use when you want strict user control over what is searched.
Require chosen knowledge bases	`require_preselected_contexts`	off	When on, users must explicitly confirm which knowledge bases to search before the tool runs. The model prompts the user to choose.	Use when your agent serves multiple completely separate domains and ambiguous routing is unacceptable.
Debug logging	`logging`	off	Logs verbose per-phase traces to the server console. Has no effect on responses.	Enable temporarily when diagnosing unexpected retrieval results; disable in production.
Utility model (optional)	`utility_model`	(empty, uses agent model)	LiteLLM model ID used for the pipeline’s internal micro-calls (routing classification, HyDE query generation, identifier detection). When empty, the agent’s own model is used.	Set to a faster or cheaper model when the agent’s primary model is large and expensive, and pipeline micro-calls don’t need its full capability.
Max knowledge searches per message	`max_steps`	`0` (no search-specific cap)	Caps the number of times the knowledge search tool may be called within a single agent turn. Once spent, the tool is disabled for the rest of that turn; the agent’s overall tool-step budget still applies.	Raise when complex questions legitimately need multiple searches. Lower to limit token spend on retrieval-heavy agents.
Search attached project items	`project_search`	on	When a chat belongs to a project, knowledge items pinned to that project are automatically included as an additional source.	Turn off when project items are not relevant to this agent’s domain.
Knowledge bases (per-source profiles)	`knowledge_bases`	`{}` (all enabled, defaults by kind)	JSON map of context ID to a profile with `enabled` (boolean), `kind` (`documents` \| `conversations` \| `records`), `instructions` (string), and `overrides` (`limit`, `expand`, `multiQuery`, `hyde`).	Configure via the wizard’s Sources step — direct JSON editing is for advanced cases only.
Routing rules	`routing`	`{ "rules": [] }` (search all)	Array of routing rules, each with a `label`, plain-text `description`, and lists of `main` and `fallback` context IDs. Empty means every enabled knowledge base is searched for every question.	Add rules when you have clearly distinct question categories that should hit different sources; omit for general-purpose agents.
Vocabulary	`vocabulary`	`{ "glossary": [], "identifiers": [], "rewrites": [], "styleHint": "" }`	Domain vocabulary: glossary term/meaning pairs, identifier sets (name, description, examples, fuzzy or exact strategy, applies-to contexts), query-rewrite rules (find → replace), and a style hint describing the documents (feeds HyDE query generation).	Add a glossary when users use abbreviations your documents don’t. Add identifier sets when users mention product names or codes that map to specific files.
Memory features	`memory`	`{ "enabled": true, "override": false, "filePrioritization": false, "queryAugmentation": true }`	Controls four memory behaviours: `enabled` (retrieve relevant memory entries alongside documents), `override` (let verified memory entries lead over documents), `filePrioritization` (pin files referenced in memory notes), `queryAugmentation` (expand queries with memory and glossary). Requires a memory context set on the agent.	Adjust when memory entries are too dominant or not influential enough.
Advanced tuning	`tuning`	`{ "topK": 5, "fallbackThreshold": 0.95, "pinBoost": 0.15, "identifierBoost": 0.15, "pageWindow": 1, "maxQueriesPerContext": 5 }`	Six retrieval knobs: `topK` — passages handed to the model (1–50); `fallbackThreshold` — similarity score below which backup sources are also searched (0–1, higher = backups used more often); `pinBoost` — reranking score added to pinned items (0–1); `identifierBoost` — score added to identifier-matched items (0–1); `pageWindow` — neighboring sections fetched around a result (0 = none); `maxQueriesPerContext` — query variations per source (1–10).	Default values work well in most deployments. Raise `topK` for broader answers; lower `fallbackThreshold` to reduce fallback noise; increase `pageWindow` for documents where context continuity matters (e.g. manuals).

Step budgets

max_steps bounds knowledge-search calls only, not the agent’s overall step budget.

Setting	Scope	Default
`max_steps` (knowledge search option)	How many times `agentic_context_search` may be called per message	`0` = no search-specific cap
Agent-level tool-step budget	Total tool steps (all tools) per message	Platform default: 10

When max_steps is 0 or unset, the search tool is not separately capped — the only limit is the agent’s overall tool-step budget. Once the max_steps budget is spent the search tool is removed from the active tool list for the rest of that turn; the model can still call other tools and will produce a final text answer. The agent-level budget (configured on the agent form, not in the knowledge-search wizard) governs all tool calls across all tools for one message.

Answer verification

The wizard’s Verification step switches on a check that runs after each finished answer: IMP extracts the answer’s factual claims, looks for a passage in that turn’s sources that settles each one, and shows the result in a panel under the answer. It never delays or alters the answer. What users see is described in Answer checking. This step is the only place in the UI that can enable the feature. It writes the agent’s claim_check JSON option:

UI label	Config key	Default	What it does	When to change it
Enable verification	`enabled`	off	Switches the check on for this agent. Off means no panel and no spend.	Turn on where answers are quoted or acted on, and the extra provider calls per answer are worth it.
Model for verification	`model`	(empty)	LiteLLM model ID for the check’s own calls. When empty, the agent’s `utility_model` is used, then the agent’s own model.	A fast, cheap model is enough — the check reads passages and judges entailment, it does not write prose.
Check depth	`fidelity`	`"fast"`	`"fast"` merges the claim-selection stages and batches sentences. `"paper"` (“Thorough”) splits every stage apart and runs one sentence per call.	Leave on Fast. `"paper"` costs roughly an order of magnitude more calls and exists for benchmarking.
Thresholds	`thresholds`	`{ warn: 0.1, alert: 0.3 }`	The share (0–1) of checked statements that are contradicted or without evidence at which the panel turns amber, then red. `warn` must stay at or below `alert`.	Raise `warn` for agents whose sources legitimately do not cover everything they are asked.
Re-search when evidence is missing	`reRetrieve`	on	When a claim finds no evidence, the check searches the knowledge base again for that claim specifically before reporting it. Bounded by `caps.maxReRetrievals`.	Turn off to cut retrieval spend; expect more statements reported as without evidence.
Also show to external users	`showToExternalUsers`	off	Whether external and guest-surface users get the panel at all. Takes effect only while Show sources to external users (Behavior step) is on.	Turn on when external viewers are meant to audit answers themselves.
(no UI control)	`completions`	`1`	How many times each stage is repeated, with majority voting over the results. Integer 1–3. Ignored outside `"paper"` fidelity, because only `"paper"` votes.	Benchmarking only; set through the API.
(no UI control)	`caps`	`{ maxSentences: 120, maxClaims: 200, maxReRetrievals: 10 }`	Per-answer work limits. Sentences past `maxSentences` are reported as `not_checked` with `status: "partial"` rather than silently costing more.	Raise through the API for agents that produce very long answers — and read the warning below first.

completions and caps have no control in the wizard but are round-tripped on save, so values you set through the API survive an operator editing other steps.

thresholds are a share between 0 and 1, not a percentage. The backend validates the whole claim_check blob and, on any validation failure, falls back to the entire schema default — which includes enabled: false. So writing { "warn": 20 } through the API does not set a 20% threshold: it silently switches verification off for that agent. The wizard cannot author such a blob, but a hand-edited option can.

Raising caps.maxSentences alone does not give you fuller coverage. Every sentence costs provider calls and the whole check must finish inside CLAIM_CHECK_TIMEOUT_MS (default 60 s) or it is cancelled with 504 — after spending whatever it spent. Raise the operator timeout alongside the cap, or the raised cap only moves where the failure happens. The full reasoning, with figures, is on the claim check API page.

Verification is also skipped for a whole turn, with no panel, whenever the check could not receive everything the answer rests on — a file attachment in the conversation, the document-viewer tool, a memory the viewer may not see, an offloaded tool output, or no sources at all. Scoring an answer against part of its evidence would report problems that are not there. The per-case list is in Answer checking.

Editions

Agentic retrieval requires the agentic-retrieval entitlement. The tool does not appear in the agent editor and returns undefined at the SDK level when the entitlement is absent. See Editions for how to activate Enterprise Edition. For the SDK factory (ExuluDefaultTools.agentic.retrieval.create.pipeline) and the full Zod schema for each JSON-typed option, see the ExuluDefaultTools reference.

Agents

Knowledge

Memory

Prompts & Skills

Routines

Evals

More

What the pipeline does

Enabling and configuring the tool

Configuration options

Step budgets

Answer verification

Editions

Next steps

Workbench

ExuluDefaultTools reference

​What the pipeline does

​Enabling and configuring the tool

​Configuration options

​Step budgets

​Answer verification

​Editions

​Next steps

Workbench

ExuluDefaultTools reference

What the pipeline does

Enabling and configuring the tool

Configuration options

Step budgets

Answer verification

Editions

Next steps