An Open-Source Research Agent That Actually Shows Its Work

You've probably seen a dozen "AI research agent" projects that promise the world and then quietly fail to reproduce their own benchmark numbers. It's a familiar frustration—you clone the repo, follow the setup, and get results that don't match the headline claims. MiroFlow is trying to solve that specific problem: it's an open-source research agent framework built around reproducible state-of-the-art results on benchmarks like GAIA, HLE, and FutureX, with the code and traces to back it up.

What It Does

MiroFlow is the core piece of the MiroMind Research Agent Project—a fully open-source system for multi-step internet research aimed at complex tasks like future event prediction. The framework itself is what lives in this repo, and it's designed to run research agents that can break down hard questions, use tools, and iterate toward answers.

The broader project is split into four parts: MiroFlow (the framework), MiroThinker (an agent that natively supports tool-assisted reasoning, in a separate repo), MiroVerse (147k premium open-source training data on Hugging Face), and the benchmark results themselves. MiroFlow is the piece you'd actually run. It requires Python 3.12+ and uses uv as its package manager, and it runs on Linux or macOS.

Why It's Cool

• The benchmarks are the pitch, and they're specific. The v0.2 release reports HLE at 27.2%, HLE-Text-Only at 29.5%, BrowserComp-EN at 33.2%, BrowserComp-ZH at 47.1%, and xBench-DeepSearch at 72.0%. The v0.3 release claims an 11% boost to GPT-5's future event prediction accuracy and a #1 ranking on the FutureX benchmark. Whether you care about those exact numbers or not, publishing them with a version history is a good sign.

• There's a published trace. The project released a GAIA Validation Trace showing 73.94% pass@1. That's a meaningful detail—it means you can inspect how the agent actually arrived at its answers rather than just trusting a score. For anyone trying to debug or build on top of an agent, traces are worth more than leaderboard positions.

• The setup is genuinely short. The README promises a start in under five minutes, and the commands back that up: clone, uv sync, copy the env template, add an OpenRouter API key, run main.py trace --config_file_name=agent_quick. No Docker orchestration, no fifteen-step dependency dance.

• There's a local demo path. A Gradio demo for local deployment is available (linked from the MiroThinker repo), plus a hosted demo at dr.miromind.ai if you just want to poke at it first.

• The training data is open too. MiroVerse ships 147k examples on Hugging Face. If you're training your own research agent rather than just running theirs, that's a resource you don't have to assemble yourself.

How to Try It

You'll need Python 3.12 or higher, uv, and Linux or macOS. Then:

# 1. Clone and setup
git clone https://github.com/MiroMindAI/MiroFlow && cd MiroFlow
uv sync

# 2. Configure API key
cp .env.template .env
# Edit .env and add your OPENROUTER_API_KEY

# 3. Run your first agent
uv run main.py trace --config_file_name=agent_quick

That last command runs a trace example—intelligent document analysis with file processing—so you can see the agent working before you point it at anything harder. From there, the repo has configs for other agent setups and the benchmark harnesses.

Find it at github.com/miromindai/MiroFlow. There's also a blog post with more detail on the benchmark results, a Discord for questions, and READMEs in Chinese and Japanese if English isn't your first language.

Final Thoughts

MiroFlow is most useful for people who want to run and inspect a research agent rather than just read about one—researchers, engineers building agent pipelines, or anyone who's been burned by unreproducible benchmark claims. The honest caveat is that it's still young (v0.1 landed in August 2025, v0.3 in September), so expect the architecture to keep shifting. But the combination of published traces, versioned benchmark history, and open training data makes it a solid starting point if you want to see how a competitive research agent is actually put together.

Follow @githubprojects for more developer tools and open source projects.