Enabling research mode

Admin

Research mode is off out of the box. Enabling it takes one step: the killswitch. A second, optional step decides which model the runs use — worth doing mainly if you want to steer costs.

What the mode does for end users is described in Research mode.

Step 1 — activate the `Research:ChatToolEnabled` killswitch

In system settings, set Research:ChatToolEnabled to on (default: false). → System settings

This setting acts as a deployment killswitch for the whole instance. It combines with the user toggle as an AND condition: a research run only starts when the killswitch is on and the user has switched research mode (the Research chip) on for that message. The chat itself then starts the run, without a model call. While the killswitch is off, the user toggle has no effect whatsoever.

Step 2 — give the research agent its own model (optional)

The seeded research agent ships with an empty provider and model. That is neither a defect nor a blocker: an empty entry means “use the deployment default”. The run then resolves provider and model from the same source chat draws its default model from — so research mode is ready to use the moment the killswitch is on.

Assigning a dedicated model is still worthwhile, for one reason: cost control. A run makes considerably more model calls than a normal answer, and for evaluating many matched documents a cheap, fast model is usually the better choice than the most expensive one available. Set it on the agents page. → Managing agents

Provider and model are always resolved as a pair — a mix of your provider and the default model (or vice versa) cannot arise.

A run can only genuinely fail if there is no usable chat provider at all — then there is no default to fall back on either. Even then the failure is not invisible: it is recorded on the run row and delivered into the conversation as a message. So the user does not wait in silence but sees that research failed, and why.

Verifying the setup

Killswitch on; at least one chat provider is configured and enabled.
In chat, switch on the research mode toggle and ask an enumerating test question (“Which documents mention topic X?”).
The turn must end within a few seconds with the placeholder notice; the magnifier in the composer turns into a spinner with a phase indicator.
After a few minutes the report must appear in the same conversation. If the run fails, “Research (aborted)”, “Research (failed)” or “Research failed” with a reason appears there instead — both are a result; silence is not. → If the run does not end normally

Permissions — what a run sees

The run is RBAC-scoped: it only enumerates the vaults and documents the triggering user is allowed to see. Research mode is therefore not a way to reach content beyond one’s own permissions. → RBAC & confidentiality

Operational notes

Desktop runtime: in the desktop app the background run only continues while the app is open — if the user closes it, no report arrives. On the next start the conversation reports the abort (“The application was shut down while the run was in progress.”). In web mode (Aspire-hosted) the run continues server-side. → Web vs. desktop
Runtime: usually a few minutes, with many matches considerably more. The maximum run time is set on the research agent (Max run minutes), 20 minutes on new installations; older installations keep their previous value (formerly 15). When it is reached, the run aborts and delivers the partial findings finished so far. → Managing agents
Cost: a run does sift through every accessible document, but that sifting happens locally, without any model call. Only the selected passages go to the model, one call per matched document. Expect a multiple of the tokens of a normal answer — but consumption follows the number of matches for the question, not the size of your knowledge base. Factor this in if you run cost budgets. → Limits (cost budgets & currency)
Model choice: because the run makes one evaluation call per matched document, a cheap, fast model is usually the better choice for the research agent than the most expensive one available.
Partial report on the agents page: if a run ended before the summary, the run view shows the banner “Partial findings, not aggregated — the run ended before the aggregation step.” above the result. The status badge alone does not tell you this: a failed run can still have a finished report.
One research run per user: each user has at most one research run started from the chat — knowledge base or web alike. A second one does not start; the user gets a normal answer with the notice “ℹ️ A background research run is already in progress. This question was therefore answered normally.” A run counts as running for at most the longest Max run minutes of the Research and Web Research agents plus 5 minutes — 45 minutes with the defaults (formerly a fixed 30). Raise the max run minutes of either agent and this lock lengthens accordingly.
Agent disabled or deleted: without an active Research agent no run starts. After the placeholder notice the user receives the message “⚠️ The research could not start: its research agent is disabled or was deleted. Please contact your administrator (Agents page).” in the conversation. If you want to switch research mode off, use the killswitch — then the chat never starts a run in the first place.
Fifth seeded agent “Web Research”: next to Research, the Agents page lists the Web Research agent (max run minutes 40 by default). It carries out the web research users start with the Web chip. It is enabled not via Research:ChatToolEnabled but in system settings, with the Allow web research switch and the Web research model. Provider and model stay empty on the agent: runs from the chat always use the model from system settings, and a model set on the agent is not used for them. → Web research · System settings
PII: the selected passages are pseudonymized before the model call; the report stays pseudonymized throughout the run and is only translated back at run end. If Presidio is unreachable, the run aborts rather than hand cleartext to the model (fail-closed) — the run checks availability itself, before and after the scan phase. → The PII shield