Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/IconDean/research-agent/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the repository, installing dependencies for both the Python backend and the React frontend, and running your first research query. The CLI path gets you to a working report in about two minutes; the optional full-stack setup adds an interactive browser UI on top.

​
Prerequisites

Before you begin, make sure you have the following installed and ready:
  • Python 3.11 or later — the agent uses modern asyncio patterns and type hints that require 3.11+.
  • Node.js 18 or later — required only if you want to run the React frontend.
  • A Gemini API key — the agent calls the Google Gemini API for all reasoning steps.
Get a free Gemini API key from Google AI Studio. Sign in with a Google account, click Create API key, and copy the generated key — you’ll need it in Step 3.

​
Installation and Setup

1

Clone the repository

Download the project source to your local machine.
git clone https://github.com/IconDean/research-agent.git
cd research-agent
2

Create and activate a Python virtual environment

Isolate the agent’s dependencies from your system Python installation.
cd research_agent
python -m venv venv
source venv/bin/activate
Once the environment is active, your terminal prompt will be prefixed with (venv).
3

Install Python dependencies

Install all required packages from the pinned requirements file.
pip install -r requirements.txt
This installs the Google Generative AI SDK, FastAPI, DuckDuckGo search, BeautifulSoup4, and supporting libraries.
4

Create the .env file

The agent reads your Gemini API key from an environment file inside the research_agent/ directory.
# still inside research_agent/
cp .env.example .env
Open .env in your editor and replace the placeholder with your actual key:
research_agent/.env
GEMINI_API_KEY=your_gemini_api_key_here
Never commit your .env file to version control. It is already listed in .gitignore, but double-check before pushing to a shared repository.
5

Run your first research query

With the virtual environment active and your .env in place, run the CLI from inside research_agent/:
python main.py "What are the latest breakthroughs in fusion energy?"
Search and fetch progress is written to stderr as the agent works:
🔍 Searching: fusion energy breakthroughs 2024
📄 Fetching: https://www.science.org/content/article/fusion-ignition
🔍 Searching: inertial confinement fusion recent results
📄 Fetching: https://www.energy.gov/articles/doe-national-laboratory-makes-history
🚫 Blocked: https://low-credibility-blog.example.com/fusion
🔍 Searching: private fusion companies milestones
📄 Fetching: https://www.nature.com/articles/d41586-024-fusion
When synthesis completes, the full markdown report is printed to stdout:
## Executive Summary

Fusion energy has seen significant milestones in 2024, with the National
Ignition Facility sustaining ignition in repeated experiments and several
private ventures announcing commercial reactor timelines...

## Key Findings

### Ignition and Energy Gain
...

### Private Sector Progress
...

## Sources

1. U.S. Department of Energy — https://www.energy.gov/...
2. Nature — https://www.nature.com/...

​
Useful CLI Flags

Once the basic workflow is running, these flags give you more control:
FlagDescription
--verbosePrint each planning step, gap analysis, and intermediate reasoning to stderr
-o report.md / --output report.mdSave the final report to a markdown file instead of printing to stdout
-q "question" / --query "question"Alternative to passing the question as a positional argument
# Save report to a file with verbose progress
python main.py --verbose -o fusion_report.md "What are the latest breakthroughs in fusion energy?"

​
Optional: Run the Full Stack

If you want the interactive React UI, start both servers after completing the steps above. Terminal 1 — FastAPI backend (from inside research_agent/ with the venv active): 
uvicorn server:app --reload --port 8000
Terminal 2 — React frontend (from the repo root): 
cd frontend
npm install
npm run dev
Open http://localhost:5173 in your browser. Type your research question into the input field and click Research — live progress events will stream in as the agent works, and the finished report will render as formatted markdown when synthesis is complete.
The React dev server proxies API requests to localhost:8000 automatically. Make sure the FastAPI process is running before submitting a query from the UI.

Build docs developers (and LLMs) love

Get started for freeTalk to us