Building AI agents, atomically
feat(example/deep-research): restore chat loop with decider + qa agents
KennyVaneetveldeb60762f88711
diff --git a/atomic-examples/deep-research/deep_research/__main__.py b/atomic-examples/deep-research/deep_research/__main__.pyindex 8c87d08..b21c87b 100644--- a/atomic-examples/deep-research/deep_research/__main__.py+++ b/atomic-examples/deep-research/deep_research/__main__.py@@ -1,4 +1,7 @@-"""Package entry point — so ``python -m deep_research "question"`` works.+"""Package entry point — ``python -m deep_research``.++With args: one-shot pipeline — ``python -m deep_research "your question"``.+Without args: drops into the chat loop.The real orchestrator lives in ``main.py``; this file is just the Pythonconvention that makes the package directly runnable.@@ -6,11 +9,11 @@ convention that makes the package directly runnable.import sys-from deep_research.main import run+from deep_research.main import chat_loop, runif __name__ == "__main__":args = sys.argv[1:]- if not args:- print('Usage: python -m deep_research "your question"', file=sys.stderr)- sys.exit(1)- run(" ".join(args))+ if args:+ run(" ".join(args))+ else:+ chat_loop()diff --git a/atomic-examples/deep-research/deep_research/agents/decider_agent.py b/atomic-examples/deep-research/deep_research/agents/decider_agent.pynew file mode 100644index 0000000..b45ad0c--- /dev/null+++ b/atomic-examples/deep-research/deep_research/agents/decider_agent.py@@ -0,0 +1,72 @@+"""+DeciderAgent — routes a follow-up user message to either more research or a direct answer.++In chat mode, every user turn after the first faces the same question:+do we already have the material to answer this, or do we need to go out+and gather more? This is that agent's entire job — one binary decision,+backed by short reasoning.++Deciding from the shared ``ResearchState`` (sources, learnings, plan)+instead of from the raw message keeps the decision grounded in what the+pipeline has actually collected, not what the model imagines it knows.+"""++import instructor+import openai+from pydantic import Field++from atomic_agents import AgentConfig, AtomicAgent, BaseIOSchema+from atomic_agents.context import SystemPromptGenerator++from deep_research.config import ChatConfig+++class DeciderInput(BaseIOSchema):+ """Input schema for the DeciderAgent."""++ user_message: str = Field(..., description="The user's latest question or follow-up.")+++class DeciderOutput(BaseIOSchema):+ """Output schema for the DeciderAgent."""++ reasoning: str = Field(+ ...,+ description="One short paragraph: what's already in the state, what's missing, and why that tips the decision.",+ )+ needs_research: bool = Field(+ ...,+ description=(+ "True if a new research pass is needed — state is empty, irrelevant, stale, or missing a key angle. "+ "False if the existing learnings already cover what the user is asking."+ ),+ )+++decider_agent = AtomicAgent[DeciderInput, DeciderOutput](+ AgentConfig(+ client=instructor.from_openai(openai.OpenAI(api_key=ChatConfig.api_key)),+ model=ChatConfig.model,+ model_api_parameters={"reasoning_effort": ChatConfig.reasoning_effort, "temperature": 0.1},+ system_prompt_generator=SystemPromptGenerator(+ background=[+ "You are a routing agent. Given the user's latest message and the current ResearchState "+ "(sources and learnings already gathered), you decide whether another research pass is warranted.",+ "You do NOT answer the question yourself. You only decide: research more, or hand off to the Q&A agent.",+ ],+ steps=[+ "Read the research state from the system context — what sources and learnings exist?",+ "Compare the user's message against those learnings. Is the answer already present, even partially?",+ "Flag a new research pass when state is empty, off-topic, outdated for a time-sensitive question, "+ "or missing an angle the user is now asking about.",+ "Otherwise, route to Q&A.",+ ],+ output_instructions=[+ "Be decisive. 'Maybe' is never the right answer.",+ "If the state is empty, always decide needs_research=true.",+ "For time-sensitive questions, check the current date in context and re-research if learnings look stale.",+ "Reasoning must cite concrete evidence from state (or its absence) — not vague intuition.",+ ],+ ),+ )+)diff --git a/atomic-examples/deep-research/deep_research/agents/qa_agent.py b/atomic-examples/deep-research/deep_research/agents/qa_agent.pynew file mode 100644index 0000000..171535a--- /dev/null+++ b/atomic-examples/deep-research/deep_research/agents/qa_agent.py@@ -0,0 +1,72 @@+"""+QAAgent — answers a user's question directly from the accumulated ResearchState.++The writer produces long-form cited reports; the QA agent is the+conversational counterpart, for when the decider has ruled that the+state already contains enough material to answer. Its job is a tight,+cited reply plus a few follow-up questions to keep the conversation+moving.++Like the writer, every factual sentence must end with a ``[Sn]``+citation marker referencing a source in the state. Uncited factual+claims are not allowed — if the state doesn't support the answer, the+decider should have routed to a new research pass instead.+"""++import instructor+import openai+from pydantic import Field++from atomic_agents import AgentConfig, AtomicAgent, BaseIOSchema+from atomic_agents.context import SystemPromptGenerator++from deep_research.config import ChatConfig+++class QAInput(BaseIOSchema):+ """Input schema for the QAAgent."""++ question: str = Field(..., description="The user's question or follow-up.")+++class QAOutput(BaseIOSchema):+ """Output schema for the QAAgent."""++ answer: str = Field(+ ...,+ description=(+ "Markdown-formatted answer. Every factual sentence must end with a [Sn] citation marker "+ "referencing a source from the research state."+ ),+ )+ follow_up_questions: list[str] = Field(+ ...,+ description="2–3 natural follow-up questions the user might want to ask next.",+ )+++qa_agent = AtomicAgent[QAInput, QAOutput](+ AgentConfig(+ client=instructor.from_openai(openai.OpenAI(api_key=ChatConfig.api_key)),+ model=ChatConfig.model,+ model_api_parameters={"reasoning_effort": ChatConfig.reasoning_effort},+ system_prompt_generator=SystemPromptGenerator(+ background=[+ "You are a research assistant. You answer user questions using ONLY the sources and learnings "+ "already present in the research state (provided in your system context).",+ "You are the conversational counterpart to the long-form writer — shorter, tighter, same citation rules.",+ ],+ steps=[+ "Read the research state — sources and learnings — from the system context.",+ "Compose a concise markdown answer grounded in the learnings. Cite each factual sentence as [Sn].",+ "Suggest 2–3 follow-up questions that naturally extend the conversation.",+ ],+ output_instructions=[+ "Only cite source IDs that actually exist in the research state.",+ "If you cannot answer from the state, say so briefly rather than inventing claims.",+ "Keep the answer tight — a few short paragraphs, not a full report.",+ "Follow-up questions should be self-contained and phrased as the user would ask them.",+ ],+ ),+ )+)diff --git a/atomic-examples/deep-research/deep_research/main.py b/atomic-examples/deep-research/deep_research/main.pyindex c66cb0e..6bca600 100644--- a/atomic-examples/deep-research/deep_research/main.py+++ b/atomic-examples/deep-research/deep_research/main.py@@ -1,12 +1,17 @@"""Deep-research orchestrator.-Reads like a recipe: plan → (per sub-topic) search → scrape → extract →-reflect → (maybe loop) → write. Each step is a call to a single-purpose-agent (see ``deep_research/agents/``) that reads from and contributes to-the shared ``ResearchState`` (see ``state.py``).+Reads like a recipe. First turn: plan → (per sub-topic) search → scrape →+extract → reflect → (maybe loop) → write. Follow-up turns in chat mode:+decider routes to either another research pass (plan → research → qa)+or straight to qa against the accumulated state.-Run: ``python -m deep_research "your question here"``+Each step is a call to a single-purpose agent (see ``deep_research/agents/``)+that reads from and contributes to the shared ``ResearchState``.++Run:+ ``python -m deep_research "your question here"`` # one-shot report+ ``python -m deep_research`` # interactive chat"""import sys@@ -14,9 +19,13 @@ import sysfrom rich.console import Consolefrom rich.markdown import Markdownfrom rich.panel import Panel+from rich.table import Table+from rich import box+from deep_research.agents.decider_agent import DeciderInput, decider_agentfrom deep_research.agents.extractor_agent import ExtractorInput, extractor_agentfrom deep_research.agents.planner_agent import PlannerInput, planner_agent+from deep_research.agents.qa_agent import QAInput, qa_agentfrom deep_research.agents.reflector_agent import ReflectorInput, reflector_agentfrom deep_research.agents.writer_agent import WriterInput, writer_agentfrom deep_research.config import ChatConfig, ResearchBudget@@ -34,37 +43,42 @@ from deep_research.tools.webpage_scraper import (console = Console()+# How many new sub-topics a follow-up research pass may add. Kept small so+# chat follow-ups don't balloon into full extra reports.+FOLLOW_UP_SUB_TOPICS = 2+def wire_context_providers(state: ResearchState) -> None:- """Register the state + current-date providers on every agent that needs them.+ """Register the state + current-date providers on every agent.- The planner is the only agent that runs before any state exists, so- it gets only the date. All others see the live ``ResearchState``.+ All agents — including the planner and the chat-mode pair (decider, qa) —+ see the live ``ResearchState``. The planner's state awareness is what+ lets follow-up re-plans extend coverage instead of duplicating it."""state_provider = ResearchStateProvider("Research State", state)date_provider = CurrentDateProvider("Current Date")- planner_agent.register_context_provider("current_date", date_provider)-- for agent in (extractor_agent, reflector_agent, writer_agent):+ for agent in (planner_agent, extractor_agent, reflector_agent, writer_agent, decider_agent, qa_agent):agent.register_context_provider("current_date", date_provider)agent.register_context_provider("research_state", state_provider)-def plan_research(state: ResearchState) -> None:- """Run the planner once to fill in ``state.plan``."""- console.rule("[bold cyan]1. Plan")- result = planner_agent.run(PlannerInput(question=state.question, num_sub_topics=ResearchBudget.num_sub_topics))+def plan_research(state: ResearchState, num_sub_topics: int = ResearchBudget.num_sub_topics) -> list[SubTopic]:+ """Run the planner, append new sub-topics to ``state.plan``, return just the new ones."""+ before = len(state.plan)+ result = planner_agent.run(PlannerInput(question=state.question, num_sub_topics=num_sub_topics))state.agent_calls += 1for st in result.sub_topics:state.plan.append(SubTopic(name=st.name, initial_queries=list(st.initial_queries)))state.queries_seen.update(st.initial_queries)- for i, st in enumerate(state.plan, 1):+ new_sub_topics = state.plan[before:]+ for i, st in enumerate(new_sub_topics, 1):console.print(f" [bold]{i}. {st.name}[/bold]")for q in st.initial_queries:console.print(f" • [dim]{q}[/dim]")+ return new_sub_topicsdef search_and_scrape(@@ -187,18 +201,122 @@ def write_report(state: ResearchState) -> tuple[str, str]:return verified.headline, verified.report-def run(question: str) -> None:- """Top-level pipeline. Reads like an outline of what 'deep research' means in this project."""- console.print(- Panel.fit(- f"[bold]Deep Research[/bold]\n{question}",- border_style="blue",- )- )+def run_initial_pipeline(question: str, state: ResearchState, search: SearXNGSearchTool, scraper: WebpageScraperTool) -> None:+ """First-turn pipeline: plan → research → write. Populates and prints state."""+ console.print(Panel.fit(f"[bold]Deep Research[/bold]\n{question}", border_style="blue"))+ state.question = question+ console.rule("[bold cyan]1. Plan")+ new_sub_topics = plan_research(state)++ console.rule("[bold cyan]2. Research")+ for sub_topic in new_sub_topics:+ research_sub_topic(sub_topic, state, search, scraper)++ headline, report = write_report(state)++ console.rule("[bold green]Report")+ console.print(Panel(f"[bold]{headline}[/bold]", border_style="green"))+ console.print(Markdown(report))+ _print_stats(state)+++def run(question: str) -> None:+ """One-shot entrypoint: plan, research, write, print the report. No chat loop."""state = ResearchState(question=question)wire_context_providers(state)+ search, scraper = _build_tools()+ run_initial_pipeline(question, state, search, scraper)+++# --- Chat loop ---------------------------------------------------------------+++def display_qa_answer(answer: str, follow_ups: list[str]) -> None:+ console.print("\n")+ console.print(Panel(Markdown(answer), title="[bold blue]Answer[/bold blue]", border_style="blue", padding=(1, 2)))++ if follow_ups:+ table = Table(show_header=True, header_style="bold cyan", box=box.ROUNDED, title="[bold]Follow-up Questions[/bold]")+ table.add_column("№", style="dim", width=4)+ table.add_column("Question", style="green")+ for i, q in enumerate(follow_ups, 1):+ table.add_row(str(i), q)+ console.print("\n")+ console.print(table)+++def answer_from_state(question: str, state: ResearchState) -> None:+ """Q&A pass against the current ResearchState. Used on follow-ups."""+ result = qa_agent.run(QAInput(question=question))+ state.agent_calls += 1+ display_qa_answer(result.answer, result.follow_up_questions)+++def research_follow_up(question: str, state: ResearchState, search: SearXNGSearchTool, scraper: WebpageScraperTool) -> None:+ """Follow-up that needs new material: plan a few new sub-topics scoped to the follow-up, research them, then QA."""+ state.question = question # the planner / providers read the live question++ console.rule("[bold cyan]Extending research")+ new_sub_topics = plan_research(state, num_sub_topics=FOLLOW_UP_SUB_TOPICS)+ for sub_topic in new_sub_topics:+ research_sub_topic(sub_topic, state, search, scraper)++ answer_from_state(question, state)+++def handle_follow_up(user_message: str, state: ResearchState, search: SearXNGSearchTool, scraper: WebpageScraperTool) -> None:+ """Route a single follow-up turn through decider → either research+QA or QA alone."""+ decision = decider_agent.run(DeciderInput(user_message=user_message))+ state.agent_calls += 1++ title = "Performing new research" if decision.needs_research else "Answering from existing state"+ border = "yellow" if decision.needs_research else "green"+ console.print("\n")+ console.print(Panel(decision.reasoning, title=f"[bold {border}]{title}[/bold {border}]", border_style=border))++ if decision.needs_research:+ research_follow_up(user_message, state, search, scraper)+ else:+ answer_from_state(user_message, state)+++def chat_loop() -> None:+ """REPL wrapper around the pipeline.++ First turn runs the full plan → research → write pipeline and prints the+ report. Every turn after that hands off to the decider, which routes to+ either another research pass (plan new sub-topics, research them, then QA)+ or straight to QA against the accumulated state. Type /exit to quit.+ """+ state = ResearchState(question="")+ wire_context_providers(state)+ search, scraper = _build_tools()++ console.print(Panel.fit("[bold blue]Deep Research — chat mode[/bold blue]\nType /exit to quit.", border_style="blue"))++ first_turn = True+ while True:+ prompt = "[bold blue]Your question:[/bold blue] " if first_turn else "[bold blue]Follow-up:[/bold blue] "+ user_message = console.input("\n" + prompt).strip()+ if not user_message:+ continue+ if user_message.lower() in ("/exit", "/quit"):+ console.print("\n[bold]Goodbye.[/bold]")+ return++ if first_turn:+ run_initial_pipeline(user_message, state, search, scraper)+ first_turn = False+ else:+ handle_follow_up(user_message, state, search, scraper)+++# --- Internals ---------------------------------------------------------------+++def _build_tools() -> tuple[SearXNGSearchTool, WebpageScraperTool]:search = SearXNGSearchTool(SearXNGSearchToolConfig(base_url=ChatConfig.searxng_base_url,@@ -206,19 +324,10 @@ def run(question: str) -> None:))scraper = WebpageScraperTool()+ return search, scraper- plan_research(state)-- console.rule("[bold cyan]2. Research")- for sub_topic in state.plan:- research_sub_topic(sub_topic, state, search, scraper)-- headline, report = write_report(state)-- console.rule("[bold green]Report")- console.print(Panel(f"[bold]{headline}[/bold]", border_style="green"))- console.print(Markdown(report))+def _print_stats(state: ResearchState) -> None:console.print(f"\n[dim]Stats: {state.agent_calls} agent calls, {len(state.sources)} sources, "f"{len(state.learnings)} learnings.[/dim]"@@ -227,7 +336,7 @@ def run(question: str) -> None:if __name__ == "__main__":args = sys.argv[1:]- if not args:- console.print('[red]Usage:[/red] python -m deep_research "your question"')- sys.exit(1)- run(" ".join(args))+ if args:+ run(" ".join(args))+ else:+ chat_loop()