MiroFlow: a fully open-source research-agent framework that tops several deep-search benchmarks

What MiroFlow is and where it fits

MiroFlow is the official implementation of the MiroMind Research Agent Project, a fully open-source system for multi-step internet research aimed at complex challenges such as future-event prediction. The README describes it as high-performance and modular, with multi-turn conversation, a broad tool ecosystem, and hierarchical sub-agent orchestration.

It is one of four components. MiroFlow itself is the agent framework in this repository. MiroThinker is a separate open-source agent that natively supports tool-assisted reasoning. MiroVerse is a dataset of 147k training examples for research-agent training. Together they form a research stack rather than a single tool. The audience is researchers and engineers building or studying deep-research agents who want a system they can reproduce and extend, not end users looking for a chat product, though a hosted demo exists.

The benchmark claims, stated precisely

MiroFlow's headline is benchmark performance, and the README is specific enough to quote. The v0.2 update reported state-of-the-art results across several agentic benchmarks: 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%. It also released a GAIA validation trace at 73.94% pass@1. The v0.3 update reported an enhanced architecture and an 11% boost to GPT-5's future-event prediction accuracy, with a number-one ranking on the FutureX benchmark.

The important word the README keeps using is reproducible: it frames the rankings as reproducible state-of-the-art performance and links an evaluation overview and a public trace. That matters because agent benchmark numbers are notoriously hard to reproduce, and a framework that ships its traces and evaluation setup is making a stronger claim than one that only reports a score. Anyone relying on these figures should still run the evaluations themselves, which the repository is set up to allow.

Getting started in under five minutes

The quickstart is short and worth following exactly, because its expected output tells you the whole chain works. The prerequisites are Python 3.12 or higher, the uv package manager, and Linux or macOS. The steps clone, sync, configure a key and run a trace:

git clone https://github.com/MiroMindAI/MiroFlow && cd MiroFlow
uv sync
cp .env.template .env
# Edit .env and add your OPENROUTER_API_KEY
uv run main.py trace --config_file_name=agent_quickstart_reading --task="What is the first country listed in the XLSX file that have names starting with Co?" --task_file_name="data/FSI-2023-DOWNLOAD.xlsx"

The README says the agent should return \boxed{Congo Democratic Republic}. The quickstart uses a document-analysis example with a bundled XLSX file, so it exercises file processing as well as reasoning. If it fails, the README's first suggestion is to check that the API key is set correctly and dependencies are installed. The reliance on an OpenRouter key in the quickstart is a small but real point: the fastest path to a running agent routes model calls through OpenRouter rather than a single provider.

Architecture, models and MCP tools

The framework's design centres on hierarchical sub-agent orchestration: a task is decomposed and delegated across sub-agents, with multi-turn conversation and tool use along the way. The README stresses robustness for real internet research, with concurrency management and fault-tolerant handling of rate-limited APIs and unstable networks, so long trajectory-collection runs do not fall over on a transient error.

Model support is broad: the README lists GPT, Claude, Gemini and Qwen among supported models. Tools are provided as MCP servers, and the repository links several, including audio transcription, a Python execution server, file reading and a reasoning server. That MCP-based tool layer is what makes the framework extensible: adding a capability means adding an MCP server rather than editing the core. pyproject.toml confirms the surrounding stack, pulling in the Anthropic, OpenAI and Google GenAI SDKs, fastmcp and the MCP libraries, plus data tooling like pandas and openpyxl for the document tasks.

Cost, deployment and reproducibility

One highlight sets MiroFlow apart from frameworks that assume a large hosted model: cost-effective deployment. The README says that powered by the open-source MiroThinker model, MiroFlow can run a research-agent service on a single RTX 4090, and that the entire stack relies on free, open-source tools, making it simple to deploy, scale and reproduce.

That is a meaningful claim for a research group or an individual without a large GPU budget. It means the framework is not only a way to orchestrate paid API models but can be run end to end on one consumer-grade card using an open model. Combined with the published traces and evaluation overview, the low-cost path is what backs up the reproducibility claim: a benchmark result is only reproducible if others can afford to run it, and a single-4090 deployment lowers that bar considerably.

Licence, maturity and what to weigh

MiroFlow is Apache-2.0 licensed, a permissive licence that suits both study and commercial use, and the repository declares a REUSE.toml for clean per-file licensing. It is trilingual, with English, Chinese and Japanese READMEs, and the code is organised around a main.py entrypoint, a config/ directory and an src/ tree with the MCP tool servers.

The things to weigh are maturity and scope. The versioning is early, the package is named run-agent at version 0.1.0, and there are no tagged releases in the repository, with progress tracked through dated news entries; the last push was on 2026-07-06. It targets Linux and macOS with Python 3.12+, so it is not a cross-platform consumer tool. And the benchmark leadership, while documented, is a moving target in a fast field, so treat the specific numbers as a snapshot and re-run the evaluations for current comparisons. For a team building serious research agents, the combination of open licence, published traces and a single-GPU deployment path is a strong reason to start here.

Editorial conclusion

Try MiroFlow if you build deep-research agents and value reproducible benchmark results over a polished product. Clone it, run uv sync, add an OpenRouter key and run the quickstart trace to confirm it works, then swap in your own models and MCP tools. Expect a research framework aimed at Linux and macOS with Python 3.12+, not a consumer app.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. MiroMindAI/MiroFlow on GitHub
4. Project website
5. README