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.mdindex 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 `Resuv 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.## Licensediff --git a/atomic-examples/deep-research/deep_research/config.py b/atomic-examples/deep-research/deep_research/config.pyindex 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 osfrom dataclasses import dataclass+from typing import Optionaldef 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.pyindex 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, timezonefrom 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.pyindex 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]")continuesource = 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 += 1console.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 += 1return 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.pyindex 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 firstregistered 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.mdindex 3928580..68b3a91 100644--- a/atomic-examples/deep-research/mermaid.md+++ b/atomic-examples/deep-research/mermaid.md@@ -1,68 +1,67 @@```mermaidflowchart 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| Send- 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;```