Skip to content

Building AI agents, atomically

fix(example/deep-research): apply PR review followups

KennyVaneetvelde91f4e71a9b01
diff --git a/atomic-examples/deep-research/README.md b/atomic-examples/deep-research/README.md
index b05d3e9..be09d62 100644
--- a/atomic-examples/deep-research/README.md
+++ b/atomic-examples/deep-research/README.md
@@ -50,22 +50,30 @@ Every agent has a single responsibility and reads / contributes to a shared `Res
uv run python -m deep_research "What is the current state of fusion energy research?"
```
+## Modes
+
+- **One-shot** (`python -m deep_research "your question"`): plan → research → write, prints a cited report and exits.
+- **Chat** (`python -m deep_research`): same first turn, then a REPL where each follow-up is routed by a `DeciderAgent` to either another research pass + Q&A or straight Q&A against the existing state.
+
## File Layout
```
deep_research/
-├── config.py # Model + connectivity + research budgets
-├── state.py # ResearchState dataclass — the one source of truth
-├── context_providers.py # Renders state into agent system prompts
+├── __main__.py # python -m deep_research entrypoint
+├── main.py # Plain orchestrator: plan → research → write (+ chat loop)
+├── config.py # Model + connectivity + research budgets
+├── state.py # ResearchState dataclass — the one source of truth
+├── context_providers.py # Renders state + current date into agent system prompts
├── agents/
│ ├── planner_agent.py # Question → sub-topics (with initial queries)
│ ├── extractor_agent.py # One scraped source → atomic claims
│ ├── reflector_agent.py # Sub-topic state → sufficient? + next queries
-│ └── writer_agent.py # Full state → cited report (draft + verify passes)
-├── tools/
-│ ├── searxng_search.py
-│ └── webpage_scraper.py
-└── main.py # Plain orchestrator: plan → research → write
+│ ├── writer_agent.py # Full state → cited report (draft + verify passes)
+│ ├── decider_agent.py # Chat mode: research more, or answer from state?
+│ └── qa_agent.py # Chat mode: cited answer from existing state
+└── tools/
+ ├── searxng_search.py
+ └── webpage_scraper.py
```
## Budgets
@@ -80,7 +88,7 @@ All limits live in `ResearchBudget` inside `config.py`. Tune to taste:
| `scrape_top_n_per_iteration` | 3 | New URLs scraped per iteration |
| `hard_call_cap` | 80 | Global safety net on total agent calls |
-Worst-case run: roughly 50 agent calls and 24 scrapes.
+Worst-case first turn with defaults: 1 plan + 4×2×(1 extract×3 sources + 1 reflect) = 33 agent calls + 2 writer passes ≈ **35 agent calls, 24 scrapes**. Chat follow-ups add a decider call plus either Q&A or another research pass; the `hard_call_cap` of 80 leaves headroom.
## License
diff --git a/atomic-examples/deep-research/deep_research/config.py b/atomic-examples/deep-research/deep_research/config.py
index 2a109e1..e5e7e3e 100644
--- a/atomic-examples/deep-research/deep_research/config.py
+++ b/atomic-examples/deep-research/deep_research/config.py
@@ -2,6 +2,7 @@
import os
from dataclasses import dataclass
+from typing import Optional
def get_api_key() -> str:
@@ -15,7 +16,7 @@ def get_searxng_base_url() -> str:
return os.getenv("SEARXNG_BASE_URL", "http://localhost:8080")
-def get_searxng_api_key() -> str:
+def get_searxng_api_key() -> Optional[str]:
return os.getenv("SEARXNG_API_KEY")
@@ -27,7 +28,7 @@ class ChatConfig:
model: str = "gpt-5-mini"
reasoning_effort: str = "low"
searxng_base_url: str = get_searxng_base_url()
- searxng_api_key: str = get_searxng_api_key()
+ searxng_api_key: Optional[str] = get_searxng_api_key()
def __init__(self):
raise TypeError("ChatConfig is not meant to be instantiated")
diff --git a/atomic-examples/deep-research/deep_research/context_providers.py b/atomic-examples/deep-research/deep_research/context_providers.py
index 56d644d..23a0122 100644
--- a/atomic-examples/deep-research/deep_research/context_providers.py
+++ b/atomic-examples/deep-research/deep_research/context_providers.py
@@ -2,17 +2,17 @@
Context providers for the deep-research pipeline.
Context providers are how runtime state reaches an agent's system prompt.
-Here we use one provider that renders the shared ``ResearchState`` (see
-``state.py``) so the extractor, reflector, and writer all see a
-consistent, up-to-date picture without having to plumb data through
-their input schemas.
-
-The planner and query agents deliberately don't use this provider — the
-planner runs before any state exists, and the query agent only needs
-what can fit cleanly into its input schema.
+We use one provider that renders the shared ``ResearchState`` (see
+``state.py``) so every agent sees a consistent, up-to-date picture without
+having to plumb data through its input schema.
+
+All six agents register the same ``ResearchStateProvider``. The planner
+uses it on follow-up turns to extend coverage instead of duplicating it;
+on the very first turn the state is empty and the provider renders a
+short "no research yet" stub.
"""
-from datetime import datetime
+from datetime import datetime, timezone
from atomic_agents.context import BaseDynamicContextProvider
@@ -60,4 +60,4 @@ class CurrentDateProvider(BaseDynamicContextProvider):
super().__init__(title=title)
def get_info(self) -> str:
- return datetime.utcnow().strftime("Today is %A, %B %d, %Y.")
+ return datetime.now(timezone.utc).strftime("Today is %A, %B %d, %Y.")
diff --git a/atomic-examples/deep-research/deep_research/main.py b/atomic-examples/deep-research/deep_research/main.py
index 856b11d..87b6c7f 100644
--- a/atomic-examples/deep-research/deep_research/main.py
+++ b/atomic-examples/deep-research/deep_research/main.py
@@ -111,6 +111,7 @@ def search_and_scrape(
page = scraper.run(WebpageScraperToolInputSchema(url=r.url, include_links=False))
if page.error or not page.content.strip():
+ console.print(f" [dim]skip {r.url}: {page.error or 'empty content'}[/dim]")
continue
source = state.register_source(url=r.url, title=r.title or page.metadata.title)
@@ -200,10 +201,12 @@ def write_report(state: ResearchState) -> tuple[str, str]:
"""Draft the report, then run a cheap verification pass over it. Returns (headline, report)."""
console.rule("[bold cyan]3. Write")
+ writer_agent.reset_history()
draft = writer_agent.run(WriterInput(question=state.question, mode="draft", draft=""))
state.agent_calls += 1
console.print(" [dim]draft written, verifying citations…[/dim]")
+ writer_agent.reset_history()
verified = writer_agent.run(WriterInput(question=state.question, mode="verify", draft=draft.report))
state.agent_calls += 1
return verified.headline, verified.report
@@ -337,8 +340,8 @@ def chat_loop() -> None:
# accumulated ResearchState.
try:
if first_turn:
- run_initial_pipeline(user_message, state, search, scraper)
first_turn = False
+ run_initial_pipeline(user_message, state, search, scraper)
else:
handle_follow_up(user_message, state, search, scraper)
except KeyboardInterrupt:
diff --git a/atomic-examples/deep-research/deep_research/state.py b/atomic-examples/deep-research/deep_research/state.py
index 817c222..9ce695b 100644
--- a/atomic-examples/deep-research/deep_research/state.py
+++ b/atomic-examples/deep-research/deep_research/state.py
@@ -10,15 +10,15 @@ The state holds three kinds of data:
- The plan: durable sub-topics the planner produced.
- Accumulated findings: sources we've seen and learnings extracted from them.
-- Deduplication sets: queries and URLs we've already touched, so the
- query agent and search loop don't re-do work.
+- Deduplication sets: queries and URLs already touched, so the search
+ loop and the planner don't re-do work on follow-up turns.
Source IDs (``S1``, ``S2``, ...) are assigned when a source is first
registered and are used throughout the pipeline as citation anchors.
"""
from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
@dataclass
@@ -55,14 +55,14 @@ class ResearchState:
learnings: list[Learning] = field(default_factory=list)
sources: list[Source] = field(default_factory=list)
- # Dedup sets — keep the search loop and query agent from repeating themselves.
+ # Dedup sets — keep the search loop and the planner from repeating themselves.
queries_seen: set[str] = field(default_factory=set)
urls_seen: set[str] = field(default_factory=set)
- # Budget counter — see config.HARD_CALL_CAP.
+ # Budget counter — see ResearchBudget.hard_call_cap.
agent_calls: int = 0
- started_at: datetime = field(default_factory=datetime.utcnow)
+ started_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
def learnings_for(self, sub_topic: str) -> list[Learning]:
return [learning for learning in self.learnings if learning.sub_topic == sub_topic]
diff --git a/atomic-examples/deep-research/mermaid.md b/atomic-examples/deep-research/mermaid.md
index 3928580..68b3a91 100644
--- a/atomic-examples/deep-research/mermaid.md
+++ b/atomic-examples/deep-research/mermaid.md
@@ -1,68 +1,67 @@
```mermaid
flowchart TD
- %% Decision Flow Diagram
- subgraph DecisionFlow["Research Decision Flow"]
- Start([User Question]) --> B{Need Search?}
- B -->|Yes| C[Generate Search Queries]
- C --> D[Perform Web Search]
- D --> E[Scrape Webpages]
- E --> F[Update Context]
- F --> G[Generate Answer]
- B -->|No| G
- G --> H[Show Answer & Follow-ups]
- H --> End([End])
+ %% Pipeline overview — first turn
+ Start([User question]) --> P[PlannerAgent]
+ P -->|sub-topics + initial queries| Loop
+
+ subgraph Loop["Per sub-topic — bounded by max_depth_per_sub_topic"]
+ S[SearXNG search] --> Sc[Webpage scraper]
+ Sc --> E[ExtractorAgent]
+ E -->|claims tagged with source_id| R{ReflectorAgent}
+ R -->|sufficient = true| Done
+ R -->|next_queries| S
end
- classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px;
- classDef decision fill:#ff9800,stroke:#f57c00,color:#fff;
- classDef process fill:#4caf50,stroke:#388e3c,color:#fff;
- classDef terminator fill:#9c27b0,stroke:#7b1fa2,color:#fff;
+ Done --> W1[WriterAgent — draft]
+ W1 --> W2[WriterAgent — verify]
+ W2 --> Out([Cited markdown report])
- class B decision;
- class C,D,E,F,G process;
- class Start,End terminator;
+ classDef agent fill:#4CAF50,stroke:#2E7D32,color:#fff;
+ classDef tool fill:#FF9800,stroke:#EF6C00,color:#fff;
+ classDef terminator fill:#9C27B0,stroke:#6A1B9A,color:#fff;
+ class P,E,W1,W2 agent;
+ class R agent;
+ class S,Sc tool;
+ class Start,Out,Done terminator;
```
```mermaid
-graph TD
- %% System Architecture Diagram
- subgraph Agents["AI Agents"]
- CA[ChoiceAgent]
- QA[QueryAgent]
- AA[AnswerAgent]
- end
+flowchart TD
+ %% Chat-mode routing — every turn after the first
+ U([Follow-up message]) --> D{DeciderAgent}
+ D -->|needs_research = true| Plan[PlannerAgent — extend coverage]
+ Plan --> Research[Search → Scrape → Extract → Reflect]
+ Research --> QA[QAAgent]
+ D -->|needs_research = false| QA
+ QA --> Reply([Cited answer + follow-ups])
- subgraph Tools["External Tools"]
- ST[SearXNG Search]
- WS[Webpage Scraper]
- end
+ classDef agent fill:#4CAF50,stroke:#2E7D32,color:#fff;
+ classDef terminator fill:#9C27B0,stroke:#6A1B9A,color:#fff;
- subgraph Context["Context Providers"]
- SC[Scraped Content]
- CD[Current Date]
- end
+ class D,Plan,QA agent;
+ class Research agent;
+ class U,Reply terminator;
+```
- %% Connections
- User -->|Question| CA
- CA -->|Search Request| QA
- QA -->|Queries| ST
- ST -->|URLs| WS
- WS -->|Content| SC
- SC -.->|Context| CA & QA & AA
- CD -.->|Date Info| CA & QA & AA
- CA -->|Direct Answer| AA
- AA -->|Response| User
+```mermaid
+graph LR
+ %% Shared state — every agent reads from / contributes to ResearchState
+ State[(ResearchState — plan, sources, learnings, dedup sets)]
- %% Styling
- classDef agent fill:#4CAF50,stroke:#2E7D32,color:#fff;
- classDef tool fill:#FF9800,stroke:#EF6C00,color:#fff;
- classDef context fill:#F44336,stroke:#C62828,color:#fff;
- classDef user fill:#9C27B0,stroke:#6A1B9A,color:#fff;
+ Planner[PlannerAgent] -->|appends sub-topics| State
+ Extractor[ExtractorAgent] -->|appends learnings tagged with source_id| State
+ Reflector[ReflectorAgent] -.->|reads| State
+ Writer[WriterAgent] -.->|reads| State
+ Decider[DeciderAgent] -.->|reads| State
+ QA[QAAgent] -.->|reads| State
+
+ State -. ResearchStateProvider .-> Planner & Extractor & Reflector & Writer & Decider & QA
+ Date[(CurrentDateProvider)] -.-> Planner & Extractor & Reflector & Writer & Decider & QA
- class CA,QA,AA agent;
- class ST,WS tool;
- class SC,CD context;
- class User user;
+ classDef agent fill:#4CAF50,stroke:#2E7D32,color:#fff;
+ classDef state fill:#F44336,stroke:#C62828,color:#fff;
+ class Planner,Extractor,Reflector,Writer,Decider,QA agent;
+ class State,Date state;
```