Search tools, AI agents, MCP servers
Submit a tool

Search iThub

Search tools, categories and collections. Type at least two characters.

Explore all tools
↑ ↓ to explore resultsEnter to open · Esc to close

MiroFlow

Apache-2.0 Python framework from MiroMind AI for multi-step research agents with MCP tools and sub-agents

Agent FrameworksOpen source

MiroFlow at a glance

Pricing
Open source
Deployment
Self-hosted
License
Open source
Platforms
macOSLinux
Language
Python
Tool type
Agent framework
Data location
Runs on your own Linux or macOS machine; prompts, files and tool calls go to the configured LLM and tool APIs (OpenRouter, OpenAI, Anthropic, Serper, Jina, E2B) unless self-hosted endpoints are set.
Maker
MiroMindAI
Founded
2025

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-worker have their own configuration and tool set and can plan independently. The core concepts page describes the five stages from intent recognition to output alignment. Setting sub_agents: null runs 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 in tool_config, and max_tool_calls_per_turn limits 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_KEY and JINA_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-serper launches the serper-search-scrape-mcp-server package 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 is all_pip_apt_pkg with 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-reading and tool-markitdown convert 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_class and model_name in the agent YAML. Kimi and MiniMax clients are part of the deleted v1.7 branch, not of main.
  • 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.py exposes trace for a single task, common-benchmark for a dataset run, prepare-benchmark to download datasets, eval-answer, score-from-log and avg-score for scoring, and print-config. All commands run through uv 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 sync

Reviews of MiroFlow

No reviews yet

Be the first to share your experience with MiroFlow.

Loading review form…

Found MiroFlow useful? Upvote it todayYour vote helps other IT teams find it in the daily ranking.

Similar to MiroFlow

Compare:MiroFlow vs Local Deep ResearchMiroFlow vs FeynmanMiroFlow vs Agent Zero

  1. LDLocal Deep ResearchSelf-hosted AI research assistant that writes cited reports.Specialized AI Agents1 views
  2. FFeynmanOpen-source AI research agent for papers, code and experimentsSpecialized AI Agents1 views
  3. Agent ZeroOpen-source AI agent framework with its own Linux workspaceAgent Frameworks8 views
  4. CrewAIMIT-licensed Python framework for role-based agent crews and event-driven flows, with the CrewAI AMP platformAgent Frameworks30 views
  5. LangChainOpen-source framework for LLM agents, with LangGraph and LangSmithAgent Frameworks30 views
  6. LlamaIndexOpen-source agent framework and LlamaParse document parsingAgent Frameworks21 views
  7. Hermes AgentSelf-hosted AI agent by Nous Research with persistent memory, self-written skills, cron jobs and chat gatewaysAgent Frameworks10 views
  8. borg (Rust agent runtime)Supervised Rust runtime that runs LLM agent pipelines with cancellation, panic isolation, budgets and checkpointsAgent Frameworks8 views