How sahilnegi4444/supervisor-based-research-agent works
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 Notebook · Readme.md Readme
Components 17
Notebook Host
Interactive Jupyter runtime that executes the prototype.
Orchestration
LangGraph-driven control flow and supervisor routing.
- LangGraph · Coordinates stateful routing and iteration between agents.
- LangChain · Underlying agent and tool abstraction layer.
Agents
Specialized supervisor and worker roles.
- Supervisor · Plans the task, delegates work, and decides next steps.
- Reader · Gathers and interprets source material.
- Writer · Synthesizes notes into a coherent research narrative.
Tools
Task-specific capabilities used by workers.
- Search Tool · Finds relevant sources via external search.
- Scraper · Fetches full-page content from discovered sources.
- Notes Maker · Captures and updates intermediate research notes.
- Writing Tool · Assembles the final written response from evidence.
- Chart Tool · Generates charts or visual summaries from research inputs.
External Services
Model and search providers used by the notebook.
- Gemini APIs · LLM backend for planning, reading, and synthesis.
- Tavily API · External search and retrieval service for live discovery.
Artifacts
Intermediate and final outputs produced during research.
- Research Notes · Accumulated working memory across research steps.
- Final Draft · Completed research synthesis produced by the workflow.
- Charts · Optional visual outputs generated from evidence or notes.
Connections 21
- 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.