Multi-Agent Research Assistant

A multi-agent research assistant built with the OpenAI Agents SDK, local SearXNG retrieval, and Reflex.

https://github.com/user-attachments/assets/9aee7d1e-7d3d-4c11-b286-a6b11fef2d8d

Enter a research question and the manager agent coordinates judges, retrieval tools, and an analyst agent to produce a polished, source-backed Markdown research report. The Reflex app renders the report in the browser and exports a formatted PDF.

Flow

User question
    |
    v
Manager agent
    |
    +--> Initial local SearXNG retrieval
    |        |
    |        v
    |    Judge agent
    |        |
    |        +--> Good enough
    |        |        |
    |        |        v
    |        |   Analyst agent --> Markdown report + sources
    |        |
    |        +--> Needs more evidence
    |                 |
    |                 v
    |          Search with Scrape
    |                 |
    |                 v
    |          Judge agent
    |                 |
    |                 +--> Good enough --> Analyst agent --> Markdown report + sources
    |                 |
    |                 +--> Still weak
    |                         |
    |                         v
    |                  Multiple targeted searches
    |                         |
    |                         v
    |                  Pick top 3 relevant URLs
    |                         |
    |                         v
    |                  Scrape selected pages
    |                         |
    |                         v
    +----------------> Analyst agent --> Markdown report + sources

Agents

Agent	Role
Manager	Orchestrates the workflow and directly calls local retrieval and scrape tools.
Judge	Evaluates the simple answer and search-with-scrape evidence before deciding whether to continue.
Analyst	Writes the final Markdown research report from the gathered evidence.

Retrieval Policy

The manager follows a staged retrieval policy:

1. Call local SearXNG retrieval for a simple first answer.
2. Ask the Judge whether that answer is sufficient (score >= 0.85).
3. If weak, run search with scrape and ask the Judge again using the same 0.85 threshold.
4. If still weak, run multiple targeted local SearXNG searches, select at least the top 3 relevant URLs, and scrape those pages.
5. Send all answer, judge, search, and scrape evidence to the Analyst for the final report.

Setup

Install dependencies:

pip install -r requirements.txt

Create a .env file from .env.template:

OPENAI_API_KEY=local
OPENAI_BASE_URL=http://localhost:8011/v1
SEARXNG_BASE_URL=https://search.furyhawk.lol
OPENAI_MODEL=unsloth/gemma-4-E4B-it-GGUF
LOCAL_TRACE_DIR=.debug_traces

search_web uses the local SearXNG endpoint configured by SEARXNG_BASE_URL.

Run the Reflex app

reflex run

Then open the local URL printed by Reflex, usually:

http://localhost:3000

App Structure

The app files live in app/:

File	Purpose
app/app.py	Reflex UI components and page registration only.
app/state.py	Reflex state, event handlers, progress logging, stop/reset behavior, and downloads.
app/research_assistant.py	OpenAI Agents SDK workflow with Manager, Judge, Analyst, and local SearXNG/url tools.
app/report_formatting.py	Markdown cleanup, browser HTML rendering, link behavior, and report CSS.
app/pdf_export.py	ReportLab-based PDF generation with headings, bullets, links, and Markdown table support.

Features

• Multi-agent workflow: Manager, Judge, and Analyst agents collaborate while the manager directly controls local retrieval tools.
• Live progress logs: Watch each agent step in real time.
• Styled Markdown report: Headings, bullets, tables, code blocks, and more render properly in the browser.
• Download report: Export the full report as a formatted PDF using ReportLab.
• Deep retrieval path: If early evidence is weak, the manager runs targeted searches and scrapes at least the top 3 relevant pages.