root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(FN-3901): add builtin research web-search provider as default

Browse Source 
The merge adds a builtin web-search research provider as the default, replacing the need for external research provider configuration and removing the setup gate for builtin defaults. Dashboard settings UX for research defaults was aligned (ResearchView, SettingsModal), CLI research commands were up

Fusion-Task-Id: FN-3901
This commit is contained in:
Fusion
2026-05-09 19:37:31 -07:00
committed by gsxdsm
parent 986aef3f8e
commit e69631ec24
21 changed files with 493 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/research.md
View File

@@ -2,7 +2,7 @@
[← Docs index](./README.md)
Fusion Research lets you create bounded research runs that search, fetch, and synthesize information from configured providers, then turn structured findings into actionable tasks — all from the dashboard, CLI, or agent sessions.
Fusion Research lets you create bounded research runs that search, fetch, and synthesize information with built-in web tools by default, then turn structured findings into actionable tasks — all from the dashboard, CLI, or agent sessions.
---
@@ -35,7 +35,7 @@ Research is **not** a replacement for reading source code or local docs — use
## Prerequisites
Research requires both the experimental flag and provider configuration before runs can execute. If setup is incomplete, the dashboard shows a setup prompt and CLI/agent tools return actionable error codes.
Research requires the experimental feature flag. Web search works out of the box using built-in agent tools, and external provider setup is optional advanced configuration.
### 1. Enable the feature flag
@@ -51,21 +51,26 @@ The Research view is gated behind an experimental feature flag. Set in global se
This also reveals the **Research Defaults** and **Research** settings sections in the dashboard Settings modal, and enables agent/CLI research tools (`fn_research_*`).
### 2. Configure a web search provider
### 2. Built-in web search is the default
Set `researchGlobalWebSearchProvider` in global settings to one of the supported backends:
By default, `researchGlobalWebSearchProvider` resolves to `"builtin"`. Search and fetch run through the agent runtime's native `WebSearch` and `WebFetch` tools, so no API key is required for baseline usage.
### 3. Optional: external search backends
You can opt into external providers in global settings:
| Provider | Required settings |
|---|---|
| `"builtin"` | No API key required (default) |
| `"searxng"` | `researchGlobalSearxngUrl` — URL of your SearXNG instance |
| `"brave"` | `researchGlobalBraveApiKey` — Brave Search API key |
| `"google"` | `researchGlobalGoogleSearchApiKey` + `researchGlobalGoogleSearchCx` — Google Custom Search credentials |
| `"tavily"` | `researchGlobalTavilyApiKey` — Tavily API key |
| `"none"` | Disables web search (other sources still work) |
| `"none"` | Disables web search (Page Fetch, Local Docs, GitHub, and LLM synthesis can still run) |
API keys are stored through Fusion's auth credential pipeline (`/api/auth/api-key`), not in settings JSON directly.
### 3. (Optional) Configure synthesis model
### 4. (Optional) Configure synthesis model
If LLM synthesis is enabled (default: on), set a synthesis provider and model:
@@ -78,7 +83,7 @@ If LLM synthesis is enabled (default: on), set a synthesis provider and model:
}
```
If no synthesis model is configured, the synthesis phase may fail with a `PROVIDER_UNAVAILABLE` error.
If no synthesis model is configured, Research falls back to the global default model lane. If no global default model is resolvable, synthesis may fail with a `PROVIDER_UNAVAILABLE` error.
### Settings hierarchy
@@ -296,10 +301,10 @@ All tools return:
Before creating runs, `fn_research_run` checks:
1. Research is enabled in settings
2. At least one search provider is configured
3. Required API keys are present
2. Web search is available (`"builtin"` by default, or an explicitly configured external backend)
3. Required API keys are present for external providers
If any check fails, the tool returns an actionable error with setup guidance instead of crashing.
If a check fails, the tool returns an actionable error with setup guidance instead of crashing. In practice, with the default `"builtin"` backend, provider-setup errors are mostly limited to explicit external-provider selections or explicit `"none"` opt-out.
### Best practices for agents
@@ -432,7 +437,7 @@ When all retries are exhausted, the run transitions to `retry_exhausted`.
| Symptom | Cause | Resolution |
|---|---|---|
| "Research is disabled in settings" | `researchGlobalEnabled` or `researchSettings.enabled` is `false` | Enable in Settings → Research |
| "Research provider is not configured" | No search provider credentials set | Add API key for your chosen provider in Settings |
| "Research provider is not configured" | Web search was explicitly disabled (`researchGlobalWebSearchProvider: "none"`) or external provider setup is incomplete | Re-enable builtin search, or finish configuring your selected external provider in Settings |
| "Missing API key for {provider}" | Auth credential not found | Configure provider credentials in Settings → Authentication |
| Run stuck in `queued` | Engine not running or no available concurrency slots | Start the project engine; check `maxConcurrentRuns` |
| Run times out | Provider slow or `maxDurationMs` too low | Increase timeout in project research settings |