What is MiroFlow?
MiroFlow is an open-source research agent framework published by MiroMind AI under the Apache License 2.0. The README presents it as one part of the MiroMind Research Agent Project, next to the MiroThinker open agent models and the MiroVerse training dataset. MiroFlow runs multi-step internet research tasks: a main agent receives the question, plans, delegates work to sub-agents and calls tools exposed through Model Context Protocol (MCP) servers, then writes a final answer. The project states that MiroThinker models were trained with agent traces collected through MiroFlow.
The framework is distributed as source code only. There are no GitHub releases or tags; installation means cloning the repository and running uv sync. The default branch, main, was last committed on January 30, 2026 (a README update), and the README news section ends with v0.3 from September 15, 2025. The most recent push to the repository, on July 6, 2026, was a force push that reset main to that January 30 commit. Pull requests adding Tavily search and a Parallel Search MCP bridge remained open as of November 17, 2026.
The documentation site describes a later v1.7 with a skill system based on SKILL.md files, agent graph orchestration, a FastAPI and React web application started by scripts/start_web.sh, and clients for models such as Kimi K2.5. The repository description also advertises a Web UI and Kimi support. That v1.7 code lived on a miroflow-1.7 branch that was deleted on April 20, 2026; as of November 17, 2026 the default branch does not contain the web application scripts or the v1.7 quickstart configuration. The code on main matches the v0.3 documentation kept in the repository under docs/mkdocs.
Benchmark figures are reported by the project itself. The README news entry for v0.2 (August 27, 2025) reports HLE 27.2%, HLE text-only 29.5%, BrowseComp-EN 33.2%, BrowseComp-ZH 47.1% and xBench-DeepSearch 72.0%, and the README table adds GAIA validation 82.4%; the GAIA guide states that 82.4% is a majority vote over three runs with Claude 3.7 Sonnet, with 72.2% as the pass@1 average of three runs, and a published trace of 165 tasks at 73.94%. For v0.3 the README reports first place on the FutureX leaderboard as of September 10, 2025, using GPT-5 inside MiroFlow. The repository description summarizes this as top-1 on five or more benchmarks. The v1.7 model comparison page states that results will be updated after testing with v1.7.
The stack is Python 3.12 or newer with uv, on Linux or macOS. Configuration uses Hydra YAML files; dependencies include the Anthropic and OpenAI SDKs, fastmcp and mcp, the E2B code interpreter, markitdown-mcp and pandas. A hosted demo runs at dr.miromind.ai, and MiroMind directs commercial inquiries to miromind.ai. Similar open-source research agents on iThub include Local Deep Research and Feynman; general agent frameworks include CrewAI.
Key capabilities
- Main agent and sub-agent orchestration A main agent recognizes the intent of a query, plans, delegates subtasks and synthesizes the final answer. Sub-agents such as the general
agent-workerhave their own configuration and tool set and can plan independently. The core concepts page describes the five stages from intent recognition to output alignment. Settingsub_agents: nullruns a single agent. - MCP tool pool Every capability is an MCP server started by a tool manager. Each tool has a YAML file in
config/tool/naming the command, module and environment variables it needs. Agents list the tools they may use intool_config, andmax_tool_calls_per_turnlimits parallel calls (10 in the quickstart configs). - Web search and scraping The searching server offers Google search through the Serper API with country, language, location, time filter and paging options, Wikipedia page content and revision history, Wayback Machine lookups and website scraping, including YouTube pages. It requires
SERPER_API_KEYandJINA_API_KEY; Jina is the default scraper and Serper the fallback. Search calls retry up to five times. Details are in the searching tools reference. - Alternative Serper search tool
tool-searching-serperlaunches theserper-search-scrape-mcp-serverpackage through npx and only needs a Serper key. The web search quickstart uses it together with an OpenRouter key. - Python code execution in E2B The code tool creates an E2B cloud sandbox, runs Python code and shell commands in it and moves files in and out and requires
E2B_API_KEY. The default sandbox template isall_pip_apt_pkgwith an 1800 second timeout. The project publishes a Dockerfile with scientific and data packages for building that template with the E2B CLI, which needs npm and Docker locally; this part of the documentation is marked as preview. - File and document reading
tool-readingandtool-markitdownconvert documents such as Excel, CSV and PDF files to text the model can work with. The first quickstart answers a question about a bundled XLSX file and expects the answer Congo Democratic Republic. - Vision, audio and reasoning tools Visual question answering on images and video uses Anthropic, OpenAI (default GPT-4o) or Gemini keys. Audio transcription defaults to gpt-4o-mini-transcribe. A reasoning tool sends hard sub-problems to a stronger model, by default Claude 3.7 Sonnet with thinking through OpenRouter or Anthropic. Open-source variants point the same functions at your own endpoints, for example Whisper large-v3-turbo through
WHISPER_BASE_URL. - LLM clients on the main branch The LLM clients overview lists ClaudeAnthropicClient, ClaudeOpenRouterClient (any OpenRouter model), GPTOpenAIClient, GPT5OpenAIClient and MiroThinkerSGLangClient. The source also contains a DeepSeek client through OpenRouter. A model is selected with
provider_classandmodel_namein the agent YAML. Kimi and MiniMax clients are part of the deleted v1.7 branch, not ofmain. - Self-hosted MiroThinker models MiroThinker models can be served with SGLang and connected through
OAI_MIROTHINKER_BASE_URL. The documented example serves MiroThinker-32B-DPO-v0.2 with tensor parallelism across 8 GPUs; the README states that a MiroThinker-based research agent service can run on a single RTX 4090. - Hydra YAML configuration Agent files in
config/combine a benchmark, an LLM block (temperature, top_p, max_tokens, provider), tools, turn limits and optional hint generation or final answer extraction with an OpenAI model. Values are read from environment variables, so keys stay in.env. The YAML configuration guide explains the structure. - Command line entry points
main.pyexposestracefor a single task,common-benchmarkfor a dataset run,prepare-benchmarkto download datasets,eval-answer,score-from-logandavg-scorefor scoring, andprint-config. All commands run throughuv run. - Benchmark harness Configs and shell scripts cover GAIA (validation, text-only and test), HLE and HLE text-only, BrowseComp English and Chinese, xBench-DeepSearch, FutureX, FinSearchComp and WebWalkerQA. Scripts run several evaluations in parallel and average the scores; GAIA data can be downloaded as a prepared archive from the MiroFlow-Benchmarks dataset on Hugging Face without a token, or generated from the gated source dataset with a token. Guides start from the evaluation overview.
- Logs and traces Each run writes per-task logs to
logs/with the message history and tool calls, which the scoring utilities read back. The project published its full GAIA validation trace with Claude 3.7 Sonnet on Hugging Face. - Requirements and API keys Python 3.12 or newer, uv, and Linux or macOS; Windows is not listed. The minimum setup needs only an OpenRouter key. Full benchmark configurations add Serper, Jina, E2B, OpenAI, Anthropic and possibly Gemini keys, and each provider bills its own usage. MiroFlow itself has no license fee.
- Web interface status The default branch has no web interface. In August 2025 the project published a Gradio demo for local deployment inside the MiroThinker repository, and the v1.7 documentation describes a FastAPI and React web app that is not on
main. MiroMind runs a hosted demo at dr.miromind.ai. - Extension guides The documentation explains how to add a new tool as an MCP server, a new LLM client and a new benchmark, and the repository accepts pull requests checked by Ruff and a PR title workflow. Questions go to GitHub Issues or the project Discord.
Where MiroFlow fits
Answering questions about local documents
The first quickstart clones the repository, runs uv sync, copies .env.template to .env with an OpenRouter key, then runs uv run main.py trace --config_file_name=agent_quickstart_reading with a task and a --task_file_name. The agent uses the reading tool with Claude 3.7 Sonnet through OpenRouter, and the same command works with other files such as PDFs by changing the path and question.
Web research with search and scraping
The second quickstart adds a Serper key and runs agent_quickstart_search with a question about current events, for example market data. The agent searches, reads pages and returns a summarized answer in a boxed final format. Full research configs combine search, scraping, code execution and reasoning tools with a sub-agent for longer tasks.
Reproducing published benchmark runs
Each benchmark has a guide with the dataset preparation command, the agent config and a script, such as GAIA validation with Claude 3.7 Sonnet, GPT-5 or MiroThinker. Runs write logs per task, and the scoring commands compute pass@1, pass@3 and majority vote figures. The project notes that FutureX submissions can use more elaborate setups than the quickstart.
Running research agents on a self-hosted model
The documented open-weights path serves a MiroThinker model with SGLang, sets the MiroThinker endpoint in .env and uses the agent_llm_mirothinker config. Tool backends still call external services unless the open-source variants for vision, audio and reasoning are pointed at self-hosted endpoints.
Comparing models under the same tools and prompts
Because the model is set in two YAML fields, the same task or benchmark can run with GPT-5, Claude, DeepSeek or MiroThinker while tools and prompts stay unchanged. The documentation presents this as a way to compare models on equal infrastructure.
Collecting agent traces for model training
MiroMind states that it used MiroFlow to collect post-training trace data for MiroThinker and released the MiroVerse dataset with 147k samples. The tracing and logging modules record full trajectories that can feed similar data collection work.
Install
git clone https://github.com/MiroMindAI/MiroFlow && cd MiroFlow && uv syncReviews of MiroFlow
Be the first to share your experience with MiroFlow.
Write a review
Loading review form…
Found MiroFlow useful? Upvote it todayYour vote helps other IT teams find it in the daily ranking.




