MiroFlow Research Agent
A multi-step research framework for complex questions, file analysis, and future-event prediction.
The README identifies the OpenRouter key, internet-research behavior, and tools for Python, file reading, search, audio, vision, and E2B, while attributing the project to the MiroMind Team; this provides source attribution and partial data-flow visibility. Deductions apply because the supplied files do not define tool permission boundaries, per-action confirmation, retention or transmission policies, secret-protection controls, external-effect safeguards, or rollback. Dependencies have constraints and are installed in CI, but many are lower-bound-only or unpinned, with no dependency audit, lockfile evidence, or vulnerability-mitigation process shown.
The README, project metadata, and CI are broadly consistent about Python 3.12, uv, and the basic installation path, and the README describes handling rate limits and unstable networks. Dependencies are declared through established package channels. Deductions apply because no implementation or tests substantiate the resilience claims, and pyproject version 0.1.0 conflicts with the README's MiroFlow v0.3 labeling. Failure guidance is limited to generic checks for the API key and installed dependencies, without an error catalog, detailed diagnostics, or recovery procedures.
The material clearly targets complex web research, future-event prediction, document analysis, and benchmark reproduction. It lists multiple model and tool integrations, provides a configuration-driven CLI entry point, and states Linux/macOS, Python 3.12, and uv requirements. Deductions apply because unsupported scenarios, safety boundaries, and tool-selection constraints are not defined; multi-provider configuration is deferred elsewhere, and Windows, resource requirements, and broader deployment environments are incompletely addressed.
The README has a strong navigational structure covering setup, concepts, capabilities, benchmarks, FAQ, contribution paths, and licensing. Installation instructions are actionable, and the complete Apache-2.0 license is present, justifying full scores for architecture, installation notes, and license. Examples and FAQ are useful but narrow, while known limitations are barely documented. Naming and release stability are weakened by the README's v0.3 label versus pyproject version 0.1.0 and package name run-agent. Dated updates, Issues, pull requests, Discord, website support, and team attribution provide maintenance channels, but there is no formal maintainer roster or explicit support commitment, and publisher identity remains unverified rather than adverse.
The quick start supplies a concrete task and expected boxed answer, while the framework combines multiple models, web research, file processing, tool use, and hierarchical sub-agents, offering substantial marginal value for complex research workflows. Deductions apply because output schemas, citation requirements, report structure, and downstream integration contracts are not systematically documented. Cost-effectiveness is asserted through open-source tooling and single-RTX-4090 deployment, but API usage, latency, hardware cost, and per-task budget evidence are absent.
Benchmark names, scores, dates, a leaderboard, a public trace, and reproduction documentation are identified, giving the claims some traceability. Deductions apply because the supplied static files do not include evaluation scripts, raw results, methodological detail, or independent sources; cross-source support is largely self-referential within the README. Claims such as reproducible, reliable, state-of-the-art, and cost-effective are not clearly separated from promotional interpretation.
- The agent can access the network and invoke Python, file-reading, search, vision, and remote-execution-style tools; deploy it in isolation and inspect actual configurations before granting filesystem, network, or execution permissions.
- Do not commit API keys to version control. The supplied material only instructs users to place a key in .env and does not document secret storage, log redaction, retention, or third-party transmission policies.
- Benchmark and reliability conclusions are primarily publisher claims in the supplied static material; verify evaluation scripts, raw traces, model settings, and costs at the pinned revision before adoption.
- Most dependencies are not fully pinned, and no security scanning or vulnerability-response process is shown; lock and audit the supply chain before production use.
- The README's v0.3 label, pyproject version 0.1.0, and run-agent package name diverge, so deployment automation should not rely solely on the displayed release identity.
What does this agent do, and when should you use it?
MiroFlow is the open-source research-agent framework in the MiroMind Research Agent Project, built for complex tasks that require iterative retrieval, reasoning, and tool use. It supports multi-turn conversations and hierarchical sub-agent orchestration with GPT, Claude, Gemini, Qwen, and other models. Its tool ecosystem includes Google Search, Python execution, file reading, audio transcription, reasoning, visual question answering, and E2B, with several tools implemented as MCP servers. Users can launch configured research tasks from the command line or access the hosted web demo; the quick-start example reads a local XLSX file and returns a specific answer. Self-hosting is documented for Linux and macOS with Python 3.12 or newer, `uv`, and an OpenRouter API key for the initial setup.
A user selects an agent configuration and submits a natural-language task through uv run main.py trace; local input can be attached with --task_file_name. MiroFlow then performs multi-turn reasoning and can coordinate hierarchical sub-agents according to the configuration. During execution it can invoke Google Search through searching_mcp_server.py, read files with reading_mcp_server.py, run Python through python_server.py, transcribe audio with audio_mcp_server.py, answer visual questions through vision_mcp_server.py, and use reasoning_mcp_server.py. It supports GPT, Claude, Gemini, Qwen, and other models, while its concurrency and fault-tolerance features are intended to handle rate-limited APIs and unstable networks. The process produces a task answer and execution trajectories suitable for collection or benchmark reproduction; the quick-start XLSX task is expected to output \boxed{Congo Democratic Republic}.
- Researchers investigating open-ended questions that require repeated web searches, tool calls, and a synthesized final answer.
- Forecasting teams evaluating workflows for future-event research on the FutureX benchmark.
- Agent-evaluation teams reproducing or comparing results on GAIA, HLE, BrowseComp, or xBench-DeepSearch.
- Analysts asking targeted questions about local XLSX data with file-reading and Python support.
- Engineering teams comparing GPT, Claude, Gemini, Qwen, or the open-source MiroThinker within one research framework.
- Teams working with mixed inputs that need file reading, audio transcription, and visual question answering in a single research workflow.
What are this agent's strengths and limitations?
- It combines multi-turn reasoning, hierarchical sub-agents, web search, file reading, Python, audio transcription, and visual question answering in one framework.
- Model support is broad: GPT, Claude, Gemini, Qwen, and the open-source MiroThinker are explicitly named.
- It publishes concrete benchmark results and reproduction guidance, including 82.4% on GAIA Validation, 27.2% on HLE, 47.1% on BrowserComp-ZH, and 72.0% on xBench-DeepSearch.
- Concurrency management and fault-tolerant execution are designed for rate-limited APIs and unstable network conditions.
- The documented MiroThinker-based stack can run a research-agent service on one RTX 4090.
- The quick-start path requires an OpenRouter API key, network access, and potentially paid model usage.
- Only Linux and macOS are listed as supported operating systems; Windows support is not documented.
- Python 3.12 or newer and
uvare mandatory prerequisites, which may require changes to an existing Python environment. - Model and tool substitutions may change behavior, cost, or capability; no direct OpenAI-key or Anthropic-key setup is shown in the supplied material.
- A hosted demo exists, but local Web UI installation and launch steps are not provided.
How do you install or deploy this agent?
The documented prerequisites are Linux or macOS, Python 3.12 or newer, and uv. Run:
git clone https://github.com/MiroMindAI/MiroFlow && cd MiroFlow
uv sync
cp .env.template .envThen edit .env and add OPENROUTER_API_KEY. The repository is licensed under Apache-2.0.
How do you use this agent?
After installing dependencies and configuring the key, run the documented first task:
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"This selects agent_quickstart_reading, reads the bundled XLSX file, and is expected to return \boxed{Congo Democratic Republic}. If it fails, verify the OpenRouter key in .env and confirm that uv sync completed. A hosted research-assistant demo is available, but the supplied material does not document a command for launching the Web UI locally.
How does this agent compare with similar options?
In the repository's table, MiroFlow reports 82.4% on GAIA Validation, above the listed results for OpenAI Deep Research at 67.4%, WebSailor-72B at 55.4%, and Manus at 73.3%. Its 72.0% xBench-DeepSearch result is above Kimi Researcher at 69.0%, WebSailor-72B at 55.0%, and DeepSeek v3.1 at 71.2%. It does not lead every reported column: its BrowserComp-EN result of 33.2% trails OpenAI Deep Research at 51.5%, while its HLE-Text score of 29.5% is slightly below DeepSeek v3.1 at 29.8%. These benchmark figures do not establish comparative production cost, latency, or reliability.
FAQ
Which credential is required to get started?
OPENROUTER_API_KEY in .env. Direct setup instructions for native OpenAI or Anthropic credentials are not included in the supplied material.Can it operate entirely offline?
Can it analyze local documents?
--task_file_name, and the documented tools include File Reading and Python. A complete list of supported file formats is not provided.