You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# SERPAPI_API_KEY=your_serpapi_key # Or choose SerpApi, register at: https://serpapi.com
48
+
```
49
+
50
+
#### Model Configuration (⚠️ Required for First Run)
51
+
52
+
v2 uses three YAML config files to drive the Researcher, Searcher, and Reporter agents. **Before first run, you must modify model names according to your LLM provider**, otherwise you may get model-not-found errors. If you want each agent to use a different model or provider, modify the `llm` section in the corresponding YAML independently; otherwise the defaults from `.env` are used.
53
+
54
+
##### Models to Configure
55
+
56
+
For balanced performance and cost, we recommend a **tiered model configuration** — choosing different models for each agent based on its role and requirements.
|`researcher.yaml`|`llm.model`|`gpt-5-2025-08-07`| Researcher Agent (main agent) | Use a stronger model (e.g. `qwen3-max` / `gpt-5`) for task planning and coordination |
61
+
|`searcher.yaml`|`llm.model`|`qwen3.5-plus`| Searcher Agent | Can use same or slightly weaker model (e.g. `qwen3.5-plus` / `MiniMax-M2.5`) |
62
+
|`searcher.yaml`|`tools.web_search.summarizer_model`|`qwen3.5-flash`| Web page summarization model (optional) | Use a fast, cheap model (e.g. `qwen3.5-flash` / `gpt-4.1-mini`) |
63
+
|`reporter.yaml`|`llm.model`|`qwen3.5-plus`| Reporter Agent | Can use same or slightly weaker model (e.g. `qwen3.5-plus` / `MiniMax-M2.5`) |
64
+
|`researcher.yaml` / `reporter.yaml`|`self_reflection.quality_check.model`|`qwen3.5-flash`| Quality check model (optional) | Use a fast, cheap model (e.g. `qwen3.5-flash` / `gpt-4.1-mini`) |
65
+
66
+
##### Common LLM Provider Examples
67
+
68
+
Modify model names in YAML files according to your provider:
69
+
70
+
**Using OpenAI:**
71
+
72
+
```yaml
73
+
# Agent configuration
74
+
llm:
75
+
service: openai
76
+
model: gpt-5-2025-08-07
77
+
openai_api_key: <OPENAI_API_KEY>
78
+
openai_base_url: <OPENAI_BASE_URL>
79
+
80
+
# Also modify quality_check and summarizer_model (defaults to OpenAI-compatible provider):
81
+
tools:
82
+
web_search:
83
+
summarizer_model: qwen3.5-flash
84
+
summarizer_api_key: <OPENAI_API_KEY>
85
+
summarizer_base_url: <OPENAI_BASE_URL>
86
+
87
+
self_reflection:
88
+
quality_check:
89
+
enabled: true
90
+
model: qwen3-flash
91
+
openai_api_key: <OPENAI_API_KEY>
92
+
openai_base_url: <OPENAI_BASE_URL>
93
+
```
94
+
95
+
**Other Compatible Endpoints:** Refer to your provider's documentation for model identifiers.
96
+
97
+
#### Search Engine Configuration
98
+
99
+
Edit `searcher.yaml` to configure search engines:
100
+
101
+
```yaml
102
+
tools:
103
+
web_search:
104
+
engines:
105
+
- exa # or serpapi (requires corresponding API key in .env)
106
+
- arxiv # arxiv requires no API key, always available
107
+
api_key: <EXA_API_KEY> # When using EXA
108
+
# Or when using SerpApi, add (uncomment):
109
+
# serpapi_provider: google # Options: google, bing, baidu
110
+
```
111
+
112
+
**Default:** If no search engine API key is configured, system will use `arxiv` (academic literature search only).
113
+
114
+
#### Advanced Configuration (Optional)
115
+
116
+
##### Web Page Summarization
117
+
118
+
Enabled by default to compress long web content, reducing context bloat, speeding up research, and saving cost:
119
+
120
+
```yaml
121
+
tools:
122
+
web_search:
123
+
enable_summarization: true
124
+
summarizer_model: qwen3.5-flash # Can switch to a cheaper model
125
+
max_content_chars: 200000 # Max content chars allowed for summarization; content beyond this is truncated
126
+
summarizer_max_workers: 15
127
+
summarization_timeout: 360
128
+
```
129
+
130
+
**Note:** Summarization makes additional LLM calls consuming more tokens, but significantly reduces the Searcher Agent's context length.
131
+
132
+
##### Quality Check
40
133
41
-
-`OPENAI_API_KEY` (key of OpenAI-compatible endpoint)
42
-
-`OPENAI_BASE_URL` (OpenAI-compatible endpoint)
43
-
- One of:
44
-
-`EXA_API_KEY` (recommended, register at [Exa](https://exa.ai), free quota available)
45
-
-`SERPAPI_API_KEY` (register at [SerpApi](https://serpapi.com), free quota available)
134
+
Both Researcher and Reporter have quality check mechanisms for verifying report generation quality:
46
135
47
-
Notes:
136
+
```yaml
137
+
self_reflection:
138
+
enabled: true
139
+
max_retries: 2 # Max check rounds
140
+
quality_check:
141
+
enabled: true
142
+
model: qwen3.5-flash
143
+
```
48
144
49
-
- v2 configs use placeholders like `<OPENAI_API_KEY>` / `<EXA_API_KEY>`, which are replaced from environment variables at runtime.
50
-
- Do not hardcode keys in scripts; keep them in `.env` (and never commit `.env`).
145
+
##### Prefix Cache (Prompt Caching)
51
146
52
-
#### Run (Researcher entry)
147
+
Explicitly triggers cache creation and hits to improve speed and reduce cost (only supported by some providers and models):
148
+
149
+
```yaml
150
+
generation_config:
151
+
force_prefix_cache: true # Auto-detects provider support
152
+
prefix_cache_roles: [system, user, assistant, tool] # Roles to explicitly request caching for
153
+
```
154
+
155
+
**Supported Providers:** DashScope, Anthropic, and some others. If encountering errors, set to `false`.
156
+
157
+
#### Configuration File Locations
158
+
159
+
v2's three YAML config files are located at:
160
+
161
+
- `projects/deep_research/v2/researcher.yaml`- Researcher main agent config
**Placeholder Note:** Placeholders like `<OPENAI_API_KEY>` / `<EXA_API_KEY>` in YAMLs are automatically replaced from `.env` environment variables at runtime. **Do not hardcode API keys in YAMLs** to reduce leak risk.
When `DR_BENCH_ROOT` is set, the script reads all queries from `$DR_BENCH_ROOT/data/prompt_data/query.jsonl` and runs them in parallel via `dr_bench_runner.py`. You can override additional parameters:
**Note:** The script automatically reads API keys from `.env` in the repository root. Ensure environment variables are properly configured before running.
220
+
62
221
#### Run in WebUI
63
222
64
223
You can also use Agentic Insight v2 from the built-in WebUI:
@@ -74,22 +233,30 @@ Then open `http://localhost:7860`, select **Deep Research**, and make sure you h
74
233
75
234
You can set them via `.env` or in WebUI **Settings**. WebUI run artifacts are stored under `webui/work_dir/<session_id>/`.
76
235
77
-
### Key configs (what to edit)
78
-
79
-
-`projects/deep_research/v2/researcher.yaml`
80
-
- Researcher orchestration prompt and workflow-level settings.
81
-
-`projects/deep_research/v2/searcher.yaml`
82
-
- Search engines (exa/arxiv/serpapi), fetching/summarization, evidence store settings.
83
-
-`projects/deep_research/v2/reporter.yaml`
84
-
- Report generation workflow and report artifacts directory.
- Outline, chapters, draft, and the assembled report artifact.
246
+
247
+
### ❓ Troubleshooting
248
+
249
+
| Error Type | Possible Cause | Solution |
250
+
|-----------|---------------|----------|
251
+
| `Model not found` / `Invalid model` | Model name in YAML doesn't match API endpoint | Check and modify `llm.model`, `summarizer_model`, and `quality_check.model` in the three YAMLs to match your provider |
252
+
| `Invalid API key` / `Unauthorized` | API key in `.env` is incorrect or expired | Verify `OPENAI_API_KEY` in `.env` is correct, or regenerate API key |
253
+
| `Search engine error` / `EXA_API_KEY not found` | Search engine API key not configured | Add `EXA_API_KEY` or `SERPAPI_API_KEY` to `.env`, or modify `searcher.yaml` to use only `arxiv` |
254
+
| 400 error / `Invalid request body` | Some generation parameters incompatible | Remove unsupported fields from `generation_config` in the YAML |
255
+
| `Timeout` / Timeout errors | Network issues or request too long | Check network connection, or increase `tool_call_timeout` value in the YAML |
256
+
| Output too short or incomplete | Model generation parameters limiting | Add or increase `max_tokens` value in `generation_config` in the YAML |
257
+
| Stuck mid-execution | Sub-agent in infinite loop or waiting | Check log files in `output_dir` to see which agent is stuck; may need to adjust `max_chat_round` |
258
+
| `.env` file not found | `.env` in wrong location | Ensure `.env` is in **repository root**, not in `projects/deep_research/` or `v2/` directories |
0 commit comments