# sahilnegi4444/supervisor-based-research-agent architecture

> Architecture diagram of the GitHub repository sahilnegi4444/supervisor-based-research-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sahilnegi4444/supervisor-based-research-agent
- Repository: https://github.com/sahilnegi4444/supervisor-based-research-agent

## Overview

1. **Repository shape**
   - This is a notebook-driven prototype, not a packaged application.
   - The only tracked artifacts are `Readme.md` and `supervisor_based_research_agent.ipynb`, so the architecture is centered around an interactive research workflow rather than a deployable service.

2. **Overall system purpose**
   - The repo implements a **hierarchical research agent**.
   - A **supervisor** coordinates specialized worker agents for reading and writing, aiming to automate research synthesis with a staged workflow.

3. **Core orchestration layer**
   - **LangGraph** is the main coordination framework.
   - It likely defines the control flow between supervisor and workers, including routing, state passing, and iteration over research tasks.
   - **LangChain** sits underneath as the agent/tooling abstraction layer.

4. **Agent hierarchy**
   - The architecture is split into at least two levels:
     - a **supervising agent** that plans and delegates,
     - **worker agents** that perform task-specific operations.
   - The README explicitly mentions **reading** and **writing** worker agents, which suggests the supervisor decides when to gather information versus when to synthesize it.

5. **Tool layer**
   - The worker agents are backed by custom tools:
     - **Reading tool** for consuming source material,
     - **Scraping tool** for fetching content from the web,
     - **Notes maker tool** for intermediate research state,
     - **Writing tool** for drafting the final narrative,
     - **Chart generator tool** for visual outputs.
   - These tools form the execution boundary between reasoning and external data handling.

6. **External data sources**
   - **Tavily API** is used for search/retrieval, which implies the research flow can start from live web discovery rather than only local context.
   - The **scraping tool** likely complements search by pulling full-page content after discovery.

7. **Model/provider boundary**
   - The notebook uses **Gemini APIs** as the LLM backend.
   - This means reasoning, planning, and synthesis are delegated to an external model provider, while the repo supplies orchestration and tools.

8. **Research data flow**
   - Typical flow is: user question or topic → supervisor → reading/search/scraping tools → notes accumulation → writing agent → final research output.
   - The chart generator can branch off from the research evidence or notes to produce visual summaries.

9. **State and intermediate artifacts**
   - The presence of a **notes maker tool** suggests the workflow preserves intermediate research state.
   - This is important architecturally because the system is not just a single-pass answer generator; it maintains structured working memory between agent steps.

10. **Execution environment**
   - The project targets **Python 3.12** and runs in a Jupyter notebook.
   - That implies an interactive, exploratory runtime where the agent graph and tools are likely tested manually and iteratively.

11. **Architectural boundaries to draw**
   - Separate the diagram into:
     - **Orchestration**: LangGraph supervisor and worker routing,
     - **Agent logic**: reading/writing responsibilities,
     - **Tools**: search, scraping, notes, charts,
     - **External services**: Gemini and Tavily,
     - **Notebook host**: interactive execution environment.
   - This repo is more about composing these boundaries than implementing a standalone backend.

12. **What is not present**
   - There is no indication of a web UI, database, queue, or deployed API service in the repository contents provided.
   - So the safest architecture diagram is a **research agent workflow in a notebook**, not a production system with persistent infrastructure.

Main entry points: [`supervisor_based_research_agent.ipynb`](https://github.com/sahilnegi4444/supervisor-based-research-agent/blob/main/supervisor_based_research_agent.ipynb) (Notebook), [`Readme.md`](https://github.com/sahilnegi4444/supervisor-based-research-agent/blob/main/Readme.md) (Readme)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Notebook Host"]
  node_notebook["Notebook<br/>jupyter runtime"]
  node_readme["Readme<br/>project guide<br/>[Readme.md]"]
end

subgraph group_orchestration["Orchestration"]
  node_langgraph{{"LangGraph<br/>workflow graph"}}
  node_langchain{{"LangChain<br/>agent toolkit"}}
end

subgraph group_agents["Agents"]
  node_supervisor(("Supervisor<br/>planner/router"))
  node_reader_agent(("Reader<br/>worker agent"))
  node_writer_agent(("Writer<br/>worker agent"))
end

subgraph group_tools["Tools"]
  node_search_tool["Search Tool<br/>retrieval tool"]
  node_scrape_tool["Scraper<br/>web extraction"]
  node_notes_tool["Notes Maker<br/>state tool"]
  node_writing_tool["Writing Tool<br/>drafting tool"]
  node_chart_tool["Chart Tool<br/>visualization tool"]
end

subgraph group_external["External Services"]
  node_gemini[("Gemini APIs<br/>llm provider")]
  node_tavily[("Tavily API<br/>search provider")]
end

subgraph group_artifacts["Artifacts"]
  node_notes["Research Notes<br/>intermediate state"]
  node_draft["Final Draft<br/>output artifact"]
  node_charts["Charts<br/>visual artifact"]
end

node_notebook -->|"runs"| node_langgraph
node_readme -->|"describes"| node_notebook
node_langgraph -->|"coordinates"| node_supervisor
node_langgraph -->|"uses"| node_langchain
node_supervisor -->|"delegates"| node_reader_agent
node_supervisor -->|"delegates"| node_writer_agent
node_supervisor -->|"updates"| node_notes_tool
node_reader_agent -->|"searches"| node_search_tool
node_reader_agent -->|"fetches"| node_scrape_tool
node_reader_agent -->|"records"| node_notes_tool
node_writer_agent -->|"drafts"| node_writing_tool
node_writer_agent -->|"visualizes"| node_chart_tool
node_writer_agent -->|"consumes"| node_notes_tool
node_search_tool -->|"queries"| node_tavily
node_scrape_tool -.->|"complements"| node_tavily
node_supervisor -->|"calls"| node_gemini
node_reader_agent -->|"calls"| node_gemini
node_writer_agent -->|"calls"| node_gemini
node_notes_tool -->|"produces"| node_notes
node_writing_tool -->|"produces"| node_draft
node_chart_tool -->|"produces"| node_charts

click node_notebook "https://github.com/sahilnegi4444/supervisor-based-research-agent/blob/main/supervisor_based_research_agent.ipynb"
click node_readme "https://github.com/sahilnegi4444/supervisor-based-research-agent/blob/main/Readme.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_notebook,node_readme toneBlue
class node_langgraph,node_langchain toneAmber
class node_supervisor,node_reader_agent,node_writer_agent toneMint
class node_search_tool,node_scrape_tool,node_notes_tool,node_writing_tool,node_chart_tool toneRose
class node_gemini,node_tavily toneIndigo
class node_notes,node_draft,node_charts toneTeal
```

## Components

### Notebook Host

Interactive Jupyter runtime that executes the prototype.

- [Notebook](https://github.com/sahilnegi4444/supervisor-based-research-agent/blob/main/supervisor_based_research_agent.ipynb): jupyter runtime · Interactive execution environment for the prototype. · `supervisor_based_research_agent.ipynb`
- [Readme](https://github.com/sahilnegi4444/supervisor-based-research-agent/blob/main/Readme.md): project guide · High-level description of the research agent workflow. · `Readme.md`

### Orchestration

LangGraph-driven control flow and supervisor routing.

- **LangGraph**: workflow graph · Coordinates stateful routing and iteration between agents.
- **LangChain**: agent toolkit · Underlying agent and tool abstraction layer.

### Agents

Specialized supervisor and worker roles.

- **Supervisor**: planner/router · Plans the task, delegates work, and decides next steps.
- **Reader**: worker agent · Gathers and interprets source material.
- **Writer**: worker agent · Synthesizes notes into a coherent research narrative.

### Tools

Task-specific capabilities used by workers.

- **Search Tool**: retrieval tool · Finds relevant sources via external search.
- **Scraper**: web extraction · Fetches full-page content from discovered sources.
- **Notes Maker**: state tool · Captures and updates intermediate research notes.
- **Writing Tool**: drafting tool · Assembles the final written response from evidence.
- **Chart Tool**: visualization tool · Generates charts or visual summaries from research inputs.

### External Services

Model and search providers used by the notebook.

- **Gemini APIs**: llm provider · LLM backend for planning, reading, and synthesis.
- **Tavily API**: search provider · External search and retrieval service for live discovery.

### Artifacts

Intermediate and final outputs produced during research.

- **Research Notes**: intermediate state · Accumulated working memory across research steps.
- **Final Draft**: output artifact · Completed research synthesis produced by the workflow.
- **Charts**: visual artifact · Optional visual outputs generated from evidence or notes.

## Connections

- Notebook → LangGraph: runs · Notebook executes the research workflow graph.
- Readme → Notebook: describes · Project guidance for the interactive prototype.
- LangGraph → Supervisor: coordinates · Graph control begins with the supervisor.
- LangGraph → LangChain: uses · Workflow relies on LangChain abstractions.
- Supervisor → Reader: delegates · Routes research and reading tasks to the reader.
- Supervisor → Writer: delegates · Routes synthesis tasks to the writer.
- Supervisor → Notes Maker: updates · Maintains intermediate working state.
- Reader → Search Tool: searches · Uses search to discover candidate sources.
- Reader → Scraper: fetches · Pulls full content from selected sources.
- Reader → Notes Maker: records · Extracts findings into research notes.
- Writer → Writing Tool: drafts · Converts notes into final prose.
- Writer → Chart Tool: visualizes · May create charts from evidence or summaries.
- Writer → Notes Maker: consumes · Reads accumulated notes as input to synthesis.
- Search Tool → Tavily API: queries · Search tool depends on Tavily for live retrieval.
- Scraper → Tavily API: complements · Scraping follows discovery from external search.
- Supervisor → Gemini APIs: calls · Supervisor reasoning is backed by Gemini.
- Reader → Gemini APIs: calls · Reading decisions and interpretation use Gemini.
- Writer → Gemini APIs: calls · Synthesis and drafting use Gemini.
- Notes Maker → Research Notes: produces · Creates the reusable research state.
- Writing Tool → Final Draft: produces · Outputs the final research draft.
- Chart Tool → Charts: produces · Creates visual artifacts from the research process.
