How iaadi4/deep-research-agent works
1. What this repo is
- This is a Python-based, multi-agent research pipeline rather than a traditional app.
- The system uses LangGraph to route a research task through specialized LLM-driven roles, then returns a synthesized markdown report.
2. Top-level runtime shape
- main.py is the entrypoint, so the project likely runs as a command-line or script-driven workflow.
- src/ contains the actual application logic; pyproject.toml and uv.lock define the Python environment and locked dependencies.
3. Core orchestration boundary
- src/graph.py is the central coordination layer.
- It likely compiles the LangGraph state machine, defines node transitions, and controls the loop between clarification, planning, research, judging, and synthesis.
4. Shared state model
- src/state.py is the shared contract between agents.
- This is the key architectural boundary: each agent reads from and writes to a common workflow state rather than passing ad hoc objects around.
- For diagramming, treat this as the “data spine” of the whole system.
5. Agent subsystem
- src/agents/ contains the role-specific LLM behaviors:
- clarifier_agent.py resolves vague user queries.
- planner_agent.py decomposes the clarified intent into research steps.
- researcher_agent.py gathers evidence using tools.
- synthesizer_agent.py turns validated evidence into the final report.
- These are not independent services; they are nodes in a single stateful graph.
6. Prompt subsystem
- src/prompts/ holds the instruction templates for each agent.
- This separates prompt engineering from orchestration logic, which is important for maintainability and diagramming: the agent “brains” are split between code and prompt assets.
7. Tooling and external data sources
- src/tools/ contains the retrieval and preprocessing utilities used by the researcher:
- tavily_search_tool.py for general web search.
- arxiv_search_tool.py for academic paper discovery.
- firecrawl_scrapping_tool.py for web page scraping/extraction.
- summarizer_tool.py for condensation and likely hallucination reduction.
- These tools form the external-data boundary of the system.
8. LLM and provider integration
- src/llm.py centralizes model setup.
- The README indicates Google Gemini via langchain-google-genai, so the agents share a common model integration rather than configuring providers separately in each agent.
9. End-to-end data flow
- The flow starts with a user query entering the clarifier.
- If ambiguous, the system loops back for clarification.
- Once scoped, the planner creates sub-tasks.
- The researcher retrieves and filters information from web and academic sources.
- The synthesizer produces the final report from the validated context.
10. Quality-control loop
- The README describes a judge-like verification step even though the file tree only explicitly shows four agents.
- Architecturally, this means the research phase is not linear: gathered evidence can be sent back for more searching when coverage is incomplete or contradictory.
- For a diagram, this is the main feedback loop in the system.
11. Verification and hallucination handling
- The system emphasizes source checking and hallucination reduction.
- The summarizer tool and judge feedback loop suggest evidence is filtered before synthesis, not just dumped into the final report.
12. External dependencies that matter architecturally
- The project depends on LangGraph for stateful orchestration, LangChain for model/prompt abstractions, and Pydantic for structured state/output validation.
- Environment variables in .env.sample indicate required external APIs, especially Google API key and Tavily API key.
13. How to draw the architecture
- The cleanest diagram is: User input → Clarifier → Planner → Researcher → Judge/verification loop → Synthesizer → Final markdown output.
- Surround the researcher with external tools/services: Tavily, arXiv, Firecrawl, and summarization.
- Place state.py as the shared workflow context that connects all nodes.
14. Key architectural takeaway
- This repo is a single-process, graph-orchestrated research engine with strong separation between orchestration, agent prompts, retrieval tools, and shared state.
- Its defining characteristic is the iterative research-and-validate loop before final synthesis, not a one-pass generation pipeline.
Main entry points: researcher_agent.py Researcher · graph.py Graph · llm.py LLM · synthesizer_agent.py Synthesizer
Components 20
Core
Graph orchestration and shared workflow state
Agents
LLM-driven roles in the research loop
- Clarifier · Resolves vague or incomplete user requests
src/agents/clarifier_agent.py - Planner · Breaks clarified intent into research steps
src/agents/planner_agent.py - Researcher · Gathers and filters evidence from tools
src/agents/researcher_agent.py - Synthesizer · Produces the final markdown report
src/agents/synthesizer_agent.py
Prompts
Instruction templates for each role
- Clarifier prompt · Instruction template for clarification
src/prompts/clarifier_prompt.py - Planner prompt · Instruction template for task decomposition
src/prompts/planner_prompt.py - Researcher prompt · Instruction template for evidence gathering
src/prompts/researcher_prompt.py - Synth prompt · Instruction template for report writing
src/prompts/synthesizer_prompt.py
Tools
Retrieval and preprocessing utilities
- Tavily · General web search retrieval
src/tools/tavily_search_tool.py - arXiv · Academic paper discovery
src/tools/arxiv_search_tool.py - Firecrawl · Web page extraction and scraping
src/tools/firecrawl_scrapping_tool.py - Summarizer · Compresses evidence and reduces noise
src/tools/summarizer_tool.py
External
Model and data-source boundaries
- Gemini · Shared model backend for the agents
- Web sources · General online pages used for research
- arXiv index · Academic paper corpus
Connections 29
- main.py → Graph: starts · CLI entrypoint launches the workflow
- Graph → State: uses · Workflow routes through shared state
- Graph → Clarifier: routes · Sends the initial query into clarification
- Graph → Planner: routes · Moves scoped intent into planning
- Graph → Researcher: routes · Executes research and evidence gathering
- Graph → Judge: loops · Routes incomplete or conflicting evidence back for more work
- Graph → Synthesizer: routes · Hands validated context to final synthesis
- LLM → Clarifier: powers · Provides the model backend
- LLM → Planner: powers · Provides the model backend
- LLM → Researcher: powers · Provides the model backend
- LLM → Synthesizer: powers · Provides the model backend
- Clarifier prompt → Clarifier: guides · Clarification instructions
- Planner prompt → Planner: guides · Planning instructions
- Researcher prompt → Researcher: guides · Research instructions
- Synth prompt → Synthesizer: guides · Synthesis instructions
- Clarifier → State: updates · Writes clarified intent back to workflow state
- Planner → State: updates · Stores research plan and steps
- Researcher → State: updates · Stores evidence and source context
- Judge → Researcher: requests more · Triggers another search pass when coverage is weak
- Researcher → Tavily: queries · Uses web search for evidence
- Researcher → arXiv: queries · Uses academic search for evidence
- Researcher → Firecrawl: extracts · Scrapes and extracts page content
- Researcher → Summarizer: condenses · Reduces retrieved material into usable notes
- Tavily → Web sources: reads · Fetches general web sources
- Firecrawl → Web sources: reads · Fetches page content from the web
- arXiv → arXiv index: reads · Fetches paper metadata and abstracts
- Synthesizer → State: reads · Consumes validated workflow context
- Synthesizer → main.py: returns · Emits the final markdown report
- Graph → LLM: uses · Centralized model setup shared across nodes