### Quick Start Setup and Execution

Source: https://miromindai.github.io/MiroFlow

Commands to clone the repository, install dependencies, configure environment variables, and execute a task.

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

# 2. Configure API keys
cp .env.template .env
# Edit .env and add your API keys (see .env.template for details)

# 3. Run your first task
bash scripts/test_single_task.sh \
  --config config/agent_quickstart.yaml \
  --task-question "What is the first country listed in the XLSX file that have names starting with Co?" \
  --file-path data/FSI-2023-DOWNLOAD.xlsx
```

--------------------------------

### Setup and run web demo

Source: https://miromindai.github.io/MiroFlow/quickstart

Clones the repository, installs dependencies, configures environment variables, and starts the FastAPI/React web application.

```bash
# 1. Clone and setup (if not done already)
git clone https://github.com/MiroMindAI/miroflow && cd miroflow
uv sync

# 2. Configure API keys (if not done already)
cp .env.template .env
# Edit .env and add your OAI_MIROTHINKER_API_KEY, SERPER_API_KEY, E2B_API_KEY

# 3. Start the web application
bash scripts/start_web.sh
```

--------------------------------

### Basic Agent Configuration

Source: https://miromindai.github.io/MiroFlow/yaml_config

Example YAML configuration for a basic iterative agent setup.

```yaml
defaults:
  - benchmark: example_dataset
  - override hydra/job_logging: none
  - _self_

entrypoint: main_agent

main_agent:
  name: main_agent
  type: IterativeAgentWithToolAndRollback
  max_turns: 30

  llm:
    _base_: config/llm/base_openai.yaml
    provider_class: GPT5OpenAIClient
    model_name: gpt-5
    max_tokens: 128000

  prompt: config/prompts/prompt_main_agent_benchmark.yaml

  tools:
    - config/tool/tool-reading.yaml

  input_processor:
    - ${input-message-generator}
  output_processor:
    - ${output-summary}
    - ${output-boxed-extractor}

input-message-generator:
  type: InputMessageGenerator
output-summary:
  type: SummaryGenerator
output-boxed-extractor:
  type: RegexBoxedExtractor

output_dir: logs
data_dir: "${oc.env:DATA_DIR,data}"
```

--------------------------------

### Setup and Run Document Analysis

Source: https://miromindai.github.io/MiroFlow/quickstart

Commands to clone the repository, synchronize dependencies, and prepare the environment configuration.

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

# 2. Configure API key (REQUIRED for LLM access)
cp .env.template .env
# Edit .env and add your OPENAI_API_KEY
```

--------------------------------

### Example Benchmark Tasks

Source: https://miromindai.github.io/MiroFlow/contribute_benchmarks

Examples of text-only and file-based tasks formatted for the metadata file.

```json
{
  "task_id": "math_001",
  "task_question": "What is the integral of x^2 from 0 to 2?",
  "ground_truth": "8/3",
  "file_path": null,
  "metadata": {
    "difficulty": "medium",
    "category": "calculus",
    "source": "custom_math_problems"
  }
}
```

```json
{
  "task_id": "doc_analysis_001",
  "task_question": "Based on the provided financial report, what was the company's revenue growth rate?",
  "ground_truth": "12.5%",
  "file_path": "reports/financial_q3_2023.pdf",
  "metadata": {
    "difficulty": "hard",
    "category": "document_analysis",
    "file_type": "pdf"
  }
}
```

--------------------------------

### Deploy vLLM Server for Whisper

Source: https://miromindai.github.io/MiroFlow/tool_audio_os

Install vLLM and start the server to host the Whisper-Large-v3-Turbo model locally.

```bash
pip install vllm==0.10.0
pip install vllm[audio]
vllm serve /path/to/whisper \
  --served-model-name whisper-large-v3-turbo \
  --task transcription
```

--------------------------------

### Run Benchmark Command

Source: https://miromindai.github.io/MiroFlow/openai-gpt5

Example command to execute the benchmark using the GPT-5 configuration.

```bash
# Run with GPT-5 on example dataset
uv run main.py common-benchmark --config_file_name=agent_llm_gpt5 output_dir="logs/test"
```

--------------------------------

### Launch the Web Application

Source: https://miromindai.github.io/MiroFlow/whats_new

Start the FastAPI and React web interface using the provided shell script.

```bash
bash scripts/start_web.sh
```

--------------------------------

### Install and Verify E2B CLI

Source: https://miromindai.github.io/MiroFlow/e2b_advanced_features

Installs the E2B command-line interface globally via npm and verifies the installation path.

```bash
# Install e2b
npm install -g @e2b/cli

# Verify installation
which e2b
```

--------------------------------

### Configure LLM Providers

Source: https://miromindai.github.io/MiroFlow

YAML configuration examples for switching between different LLM providers and models.

```yaml
# GPT-5
llm:
  provider_class: GPT5OpenAIClient
  model_name: gpt-5

# Claude 3.7 Sonnet
llm:
  provider_class: ClaudeAnthropicClient
  model_name: claude-3-7-sonnet-20250219

# MiroThinker (open-source, self-hosted)
llm:
  provider_class: MiroThinkerSGLangClient
  model_name: mirothinker-v1.5
```

--------------------------------

### Define Reasoning Input Examples

Source: https://miromindai.github.io/MiroFlow/tool_reasoning_os

Examples of complex prompts for mathematical, logical, and strategic reasoning tasks.

```python
question = """
Solve this complex optimization problem:
A company wants to minimize costs while maximizing production. 
Given constraints: 2x + 3y ≤ 100, x + y ≤ 50, x ≥ 0, y ≥ 0
Cost function: C = 5x + 8y
Production function: P = 3x + 4y
Find the optimal values of x and y.
"""
```

```python
question = """
Three people are in a room: Alice, Bob, and Charlie. 
- Alice says: "Bob is lying"
- Bob says: "Charlie is lying" 
- Charlie says: "Alice is lying"
If exactly one person is telling the truth, who is it?
"""
```

```python
question = """
Design a strategy for a startup to enter a competitive market 
with limited resources. Consider market analysis, competitive 
positioning, resource allocation, and risk mitigation.
"""
```

--------------------------------

### Switch Models Configuration

Source: https://miromindai.github.io/MiroFlow/llm_clients_overview

Examples of how to swap between different LLM providers by modifying the provider_class and model_name fields.

```yaml
# GPT-5
main_agent:
  llm:
    provider_class: GPT5OpenAIClient
    model_name: gpt-5

# Claude 3.7 Sonnet
main_agent:
  llm:
    provider_class: ClaudeAnthropicClient
    model_name: claude-3-7-sonnet-20250219

# MiroThinker (open-source, self-hosted)
main_agent:
  llm:
    provider_class: MiroThinkerSGLangClient
    model_name: mirothinker-v1.5
```

--------------------------------

### Reinstall dependencies

Source: https://miromindai.github.io/MiroFlow/quickstart

Command to ensure all project dependencies are correctly installed.

```bash
uv sync  # Reinstall dependencies
```

--------------------------------

### Custom E2B Dockerfile Configuration

Source: https://miromindai.github.io/MiroFlow/e2b_advanced_features

A template Dockerfile for E2B sandboxes, including base image selection, Python dependency installation, and necessary system-level packages for scientific computing and data processing.

```dockerfile
# You can use most Debian-based base images
FROM e2bdev/code-interpreter

# Update package list and install Python 3.10 and pip
RUN apt-get update && apt-get install -y \
    portaudio19-dev \
    && rm -rf /var/lib/apt/lists/*

RUN python3 -m pip install --no-cache-dir --upgrade pip setuptools wheel

# Install dependencies and customize sandbox
RUN python3 -m pip install --no-cache-dir \
    Flask \
    IPython \
    Pillow \
    PyGithub \
    PyMuPDF \
    PyPDF2 \
    arch \
    arm-pyart \
    arxiv \
    ase \
    astropy \
    astroquery \
    awscli \
    beautifulsoup4 \
    biopython \
    boto3 \
    brian2 \
    cairosvg \
    cgt \
    chardet \
    chess \
    cinemagoer \
    clifford \
    contextily \
    control \
    cryptography \
    cvxpy \
    datasets \
    descarteslabs \
    duckduckgo-search \
    edalize \
    english_words \
    ephem \
    esp-docs \
    flask \
    folium \
    geopandas \
    geopy \
    google-search-results \
    googlesearch-python \
    googletrans \
    habanero \
    helics \
    hijri_converter \
    imbalanced-learn \
    inflect \
    isbnlib \
    kaggle \
    lifelines \
    lxml \
    lxml_html_clean \
    mapclassify \
    markdown \
    'matplotlib>=3.8' \
    mendeleev \
    metpy \
    music21 \
    networkx \
    nipype \
    numba \
    'numpy>=2' \
    opencv-python \
    openpyxl \
    'pandas>=2' \
    pandas_datareader \
    parsl \
    pdf2image \
    pdfminer \
    pdfplumber \
    periodictable \
    plotly \
    polars \
    psycopg2-binary \
    pulp \
    pyXSteam \
    pybel \
    pycryptodome \
    pydot \
    pygplates \
    pymatgen \
    pymupdf \
    pypdf2 \
    pypinyin \
    pyscf \
    pytesseract \
    python-docx \
    pytube \
    pywavelets \
    rdflib \
    reportlab \
    requests \
    requests-html \
    scanpy \
    scikit-image \
    scikit-learn \
    scipy \
    scvelo \
    seaborn \
    selenium \
    semanticscholar \
    shap \
    shapely \
    siphon \
    skyfield \
    smbus2 \
    snappy \
    spglib \
    sphinx \
    splink \
    statsmodels \
    stockfish \
    sympy \
    tabulate \
    torch \
    torchvision \
    transformers \
    uncertainpy \
    us \
    virtualenv \
    wbdata \
    webdriver-manager \
    wikipedia-api \
    wolframalpha \
    wordfreq \
    yfinance \
    yt-dlp \
    docx2txt \
    rdkit \
    stockfish \
    yfinance \
    seaborn \
    python-pptx \
    pyaudio \
    pyshp \
    SpeechRecognition \
    waybackpy

RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    # ── Basic build & Python ───────────────────────────────
    build-essential gfortran cmake pkg-config git curl wget ca-certificates \
    # ── scientific computing ───────────────────────────────────────
    libopenblas-dev liblapack-dev libatlas-base-dev \
    libssl-dev libffi-dev zlib1g-dev \
    # ── image / OpenCV / Pillow ─────────────────────────
    libgl1 libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 libxrender1 \
    libjpeg-dev libpng-dev libwebp-dev libfreetype6-dev libopenjp2-7 liblcms2-dev \
    # ── video / audio ──────────────────────────────────
    ffmpeg libsndfile1 sox portaudio19-dev \
    # ── PDF / doc / OCR ───────────────────────────────
    poppler-utils pdfgrep ghostscript \
    tesseract-ocr tesseract-ocr-deu \
    libxml2-dev libxslt1-dev \
    # ── other tools ───────────────────────────────────────
    imagemagick unlambda stockfish \
    unzip zip tar nano && \
    apt-get clean && rm -rf /var/lib/apt/lists/*
```

--------------------------------

### Initialize Environment Configuration

Source: https://miromindai.github.io/MiroFlow/download_datasets

Copy the template file to create the local environment configuration.

```bash
cp .env.template .env
```

--------------------------------

### Launch SGLang Server for Local Deployment

Source: https://miromindai.github.io/MiroFlow/tool_vqa_os

Deploy the Qwen2.5-VL-72B-Instruct model locally using SGLang version 0.5.2 for optimal performance.

```bash
python3 -m sglang.launch_server \
  --model-path /path/to/Qwen2.5-VL-72B-Instruct \
  --tp 8 --host 0.0.0.0 --port 1234 \
  --trust-remote-code --enable-metrics \
  --log-level debug --log-level-http debug \
  --log-requests --log-requests-level 2 --show-time-cost
```

--------------------------------

### Sports Prediction Task Example

Source: https://miromindai.github.io/MiroFlow/futurex

Example of a sports outcome prediction task format.

```text
Task: "Brighton vs. Tottenham (resolved around 2025-09-21 (GMT+8))
A. Brighton win on 2025-09-20
B. Brighton vs. Tottenham end in a draw
C. Tottenham win on 2025-09-20"
Expected Format: \boxed{A}, \boxed{B}, or \boxed{C}
```

--------------------------------

### Set Up Benchmark Data Directory

Source: https://miromindai.github.io/MiroFlow/contribute_benchmarks

Shell commands to create the required directory structure and verify file placement for the benchmark dataset.

```bash
# Create the benchmark data directory
mkdir -p data/your-benchmark

# Copy your dataset files
cp your-dataset/* data/your-benchmark/

# Verify the structure
ls -la data/your-benchmark/
```

--------------------------------

### Environment Configuration

Source: https://miromindai.github.io/MiroFlow/gaia_validation_prerequisites

Initialize the environment file and set the required Hugging Face token and data directory.

```bash
cp .env.template .env
```

```bash
HF_TOKEN="your-actual-huggingface-token-here"
DATA_DIR="data/"
```

--------------------------------

### Political Prediction Task Example

Source: https://miromindai.github.io/MiroFlow/futurex

Example of a political event prediction task format.

```text
Task: "Will the 2025 Guinea referendum pass? (resolved around 2025-09-21 (GMT+8))"
Expected Format: \boxed{Yes} or \boxed{No}
```

--------------------------------

### Run BrowseComp-EN Evaluation

Source: https://miromindai.github.io/MiroFlow/browsecomp_en

Executes the benchmark evaluation using the specified configuration file.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_browsecomp-en_mirothinker.yaml \
  benchmark.execution.max_concurrent=30 \
  output_dir="logs/browsecomp-en/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### wiki_get_page_content

Source: https://miromindai.github.io/MiroFlow/tool_searching

Get specific Wikipedia page content for entities and return structured information.

```APIDOC
## wiki_get_page_content(entity: str, first_sentences: int = 10)

### Description
Get specific Wikipedia page content for entities (people, places, concepts, events) and return structured information.

### Parameters
- **entity** (str) - Required - The entity to search for in Wikipedia
- **first_sentences** (int) - Optional - Number of first sentences to return. Set to 0 for full content. Default: 10

### Returns
- **str** - Formatted content containing page title, introduction/full content, and URL
```

--------------------------------

### Run Benchmark Command

Source: https://miromindai.github.io/MiroFlow/deepseek

Execute the benchmark using the specified configuration file.

```bash
# Run with DeepSeek v3.1 Chat (OpenRouter) on example dataset
uv run main.py common-benchmark --config_file_name=agent_llm_deepseek_openrouter output_dir="logs/test"
```

--------------------------------

### Run Futurex-Online Evaluation

Source: https://miromindai.github.io/MiroFlow/futurex

Execute the benchmark using a specific configuration file and output directory.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_gaia-validation-165_mirothinker.yaml \
  benchmark=futurex \
  output_dir="logs/futurex/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Execute Benchmark Preparation Script

Source: https://miromindai.github.io/MiroFlow/download_datasets

Run the shell script to initiate the download process for all benchmark datasets.

```bash
bash scripts/run_prepare_benchmark.sh
```

--------------------------------

### Execute Benchmark Tests

Source: https://miromindai.github.io/MiroFlow/contribute_benchmarks

Commands to run initial integration tests on a subset of data or execute a full evaluation of the benchmark.

```bash
uv run main.py common-benchmark \
  --config_file_name=agent_quickstart_reading \
  benchmark=your-benchmark \
  benchmark.execution.max_tasks=3 \
  output_dir="logs/test-your-benchmark/$(date +"%Y%m%d_%H%M")"
```

```bash
uv run main.py common-benchmark \
  --config_file_name=agent_quickstart_reading \
  benchmark=your-benchmark \
  output_dir="logs/your-benchmark/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Prepare WebWalkerQA Dataset

Source: https://miromindai.github.io/MiroFlow/webwalkerqa

Downloads and standardizes the WebWalkerQA dataset into a JSONL file.

```bash
uv run -m miroflow.utils.prepare_benchmark.main get webwalkerqa
```

--------------------------------

### Run Benchmark via CLI

Source: https://miromindai.github.io/MiroFlow/yaml_config

Execute a benchmark run directly from the command line using uv.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_gaia-validation-165_mirothinker.yaml \
  benchmark.execution.max_concurrent=30 \
  output_dir="logs/gaia-validation-165/run_1"
```

--------------------------------

### Deploy SGLang Server for Local Reasoning

Source: https://miromindai.github.io/MiroFlow/tool_reasoning_os

Launch the SGLang server locally to host the reasoning model with specified performance parameters.

```bash
python3 -m sglang.launch_server \
  --model-path /path/to/Qwen3-235B-A22B-Thinking-2507 \
  --tp 8 --host 0.0.0.0 --port 1234 \
  --trust-remote-code --enable-metrics \
  --log-level debug --log-level-http debug \
  --log-requests --log-requests-level 2 \
  --show-time-cost --context-length 131072
```

--------------------------------

### Run WebWalkerQA Evaluation

Source: https://miromindai.github.io/MiroFlow/webwalkerqa

Executes the benchmark evaluation using the specified configuration file.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_webwalkerqa_mirothinker.yaml \
  benchmark.execution.max_concurrent=30 \
  output_dir="logs/webwalkerqa/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Execute Benchmark Command

Source: https://miromindai.github.io/MiroFlow/openrouter-claude-3.7-sonnet

Command to run the agent using the specified configuration file and output directory.

```bash
# Run with Claude 3.7 Sonnet on example dataset
uv run main.py common-benchmark --config_file_name=agent_llm_claude37sonnet output_dir="logs/test"
```

--------------------------------

### Configure Local Deployment Environment

Source: https://miromindai.github.io/MiroFlow/tool_audio_os

Use these settings when connecting the MCP server to a local vLLM instance.

```bash
WHISPER_MODEL_NAME="openai/whisper-large-v3-turbo"
WHISPER_API_KEY="dummy_key"  # Not required for local deployment
WHISPER_BASE_URL="http://localhost:8000/v1"
```

--------------------------------

### Configure Local Deployment Environment

Source: https://miromindai.github.io/MiroFlow/tool_reasoning_os

Set environment variables to point the reasoning tool to a locally running SGLang instance.

```bash
REASONING_MODEL_NAME="Qwen/Qwen3-235B-A22B-Thinking-2507"
REASONING_API_KEY="dummy_key"  # Not required for local deployment
REASONING_BASE_URL="http://localhost:1234/v1/chat/completions"
```

--------------------------------

### List benchmark files

Source: https://miromindai.github.io/MiroFlow/contribute_benchmarks

Use this command to view all files generated within a specific benchmark directory.

```bash
ls -la logs/your-benchmark/
```

--------------------------------

### Benchmark Settings

Source: https://miromindai.github.io/MiroFlow/yaml_config

Configuration parameters for benchmark execution.

```yaml
name: "your-benchmark"
data:
  data_dir: "${data_dir}/your-data"
execution:
  max_tasks: null      # null = no limit
  max_concurrent: 3    # Parallel tasks
  pass_at_k: 1         # Attempts per task
```

--------------------------------

### Run xbench-DeepSearch Evaluation

Source: https://miromindai.github.io/MiroFlow/xbench_ds

Executes the benchmark using the specified configuration and output directory.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_xbench-ds_mirothinker.yaml \
  benchmark.execution.max_concurrent=30 \
  output_dir="logs/xbench-ds/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Verify E2B Template Build

Source: https://miromindai.github.io/MiroFlow/e2b_advanced_features

Use this command to list and verify that your custom sandbox template has been built successfully.

```bash
E2B_ACCESS_TOKEN=${your-token} e2b template list
```

--------------------------------

### Configure Environment Variables

Source: https://miromindai.github.io/MiroFlow/yaml_config

Define API keys for LLM providers, tools, and optional directory settings in your environment configuration.

```bash
OPENROUTER_API_KEY="your_key"
ANTHROPIC_API_KEY="your_key"
OPENAI_API_KEY="your_key"
OAI_MIROTHINKER_API_KEY="your_key"
OAI_MIROTHINKER_BASE_URL="your_url"

# Tools
SERPER_API_KEY="your_key"
JINA_API_KEY="your_key"
E2B_API_KEY="your_key"

# Optional
DATA_DIR="data/"
CHINESE_CONTEXT="false"
```

--------------------------------

### Configure GPT-5 API keys in .env

Source: https://miromindai.github.io/MiroFlow/gaia_validation_gpt5

Define necessary API keys for search, code execution, vision, and LLM provider services in the .env file.

```bash
# Search and web scraping capabilities
SERPER_API_KEY="your-serper-api-key"
JINA_API_KEY="your-jina-api-key"

# Code execution environment
E2B_API_KEY="your-e2b-api-key"

# Vision understanding capabilities
ANTHROPIC_API_KEY="your-anthropic-api-key"
GEMINI_API_KEY="your-gemini-api-key"

# Primary LLM provider, LLM judge, reasoning, and hint generation
OPENAI_API_KEY="your-openai-api-key"
OPENAI_BASE_URL="https://api.openai.com/v1"
```

--------------------------------

### Configure Reasoning Tool Environment Variables

Source: https://miromindai.github.io/MiroFlow/tool_reasoning_os

Set these variables in the tool-reasoning-os.yaml configuration file to define the model and API endpoint.

```bash
# API for Open-Source Reasoning Tool (for benchmark testing)
REASONING_MODEL_NAME="Qwen/Qwen3-235B-A22B-Thinking-2507"
REASONING_API_KEY=your_reasoning_key
REASONING_BASE_URL="https://your_reasoning_base_url/v1/chat/completions"
```

--------------------------------

### Configure Environment Variables

Source: https://miromindai.github.io/MiroFlow/download_datasets

Set the Hugging Face token and data directory path in the .env file.

```text
# Required: Your Hugging Face token for dataset access
HF_TOKEN="your-actual-huggingface-token-here"

# Data directory path
DATA_DIR="data/"
```

--------------------------------

### Configure MiroFlow Environment Variables

Source: https://miromindai.github.io/MiroFlow/mirothinker

Sets the API key and base URL in the .env file to point to the local SGLang server instance.

```text
OAI_MIROTHINKER_API_KEY="dummy_key"
OAI_MIROTHINKER_BASE_URL="http://localhost:61005/v1"
```

--------------------------------

### Run Task Script

Source: https://miromindai.github.io/MiroFlow/llm_clients_overview

Command to execute a single task using a specified configuration file.

```bash
bash scripts/test_single_task.sh \
  --config config/your_config.yaml \
  --task-question "Your task here"
```

--------------------------------

### Run FinSearchComp Evaluation

Source: https://miromindai.github.io/MiroFlow/finsearchcomp

Executes the benchmark evaluation using a specified configuration file and output directory.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_gaia-validation-165_mirothinker.yaml \
  benchmark=finsearchcomp \
  output_dir="logs/finsearchcomp/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Download BrowseComp-EN Dataset

Source: https://miromindai.github.io/MiroFlow/browsecomp_en

Downloads the standardized BrowseComp-EN test dataset to the local data directory.

```bash
uv run -m miroflow.utils.prepare_benchmark.main get browsecomp-test
```

--------------------------------

### Download Pre-configured Dockerfile

Source: https://miromindai.github.io/MiroFlow/e2b_advanced_features

Retrieves the official MiroFlow Dockerfile required for sandbox template creation.

```bash
wget https://github.com/MiroMindAI/miroflow/blob/main/docs/e2b.Dockerfile
```

--------------------------------

### Configure Environment Variables

Source: https://miromindai.github.io/MiroFlow/browsecomp_en

Required API keys and base URLs for model access, search, scraping, and code execution.

```bash
# MiroThinker model access
OAI_MIROTHINKER_API_KEY="your-mirothinker-api-key"
OAI_MIROTHINKER_BASE_URL="http://localhost:61005/v1"

# Search and web scraping
SERPER_API_KEY="xxx"
JINA_API_KEY="xxx"

# Code execution
E2B_API_KEY="xxx"
```

--------------------------------

### Download xbench-DeepSearch Dataset

Source: https://miromindai.github.io/MiroFlow/xbench_ds

Downloads and processes the benchmark dataset into a standardized JSONL file.

```bash
uv run -m miroflow.utils.prepare_benchmark.main get xbench-ds
```

--------------------------------

### Configure Open-Source VQA Tool Environment Variables

Source: https://miromindai.github.io/MiroFlow/tool_vqa_os

Set these variables in the tool-image-video-os.yaml configuration file to define the model and API endpoint.

```bash
# API for Open-Source VQA Tool (for benchmark testing)
VISION_MODEL_NAME="Qwen/Qwen2.5-VL-72B-Instruct"
VISION_API_KEY=your_vision_key
VISION_BASE_URL="https://your_vision_base_url/v1/chat/completions"
```

--------------------------------

### Define Benchmark Configuration

Source: https://miromindai.github.io/MiroFlow/contribute_benchmarks

YAML configuration for setting dataset paths, metadata filenames, and execution parameters like concurrency and task limits.

```yaml
defaults:
  - default          # Use default benchmark settings
  - _self_           # Allow overrides in this file

name: "your-benchmark"

data:
  data_dir: "${data_dir}/your-benchmark"        # Dataset location
  metadata_file: "standardized_data.jsonl"     # Metadata filename

execution:
  max_tasks: null          # null = no limit, number = max tasks to run
  max_concurrent: 5        # Number of parallel task executions
  pass_at_k: 1             # Number of attempts per task for pass@k evaluation

# LLM judge configuration for evaluation
openai_api_key: "${oc.env:OPENAI_API_KEY,???}"
```

--------------------------------

### Configure Local Deployment Environment Variables

Source: https://miromindai.github.io/MiroFlow/tool_vqa_os

Set these variables when running the model locally; the API key is not required for local instances.

```bash
VISION_MODEL_NAME="Qwen/Qwen2.5-VL-72B-Instruct"
VISION_API_KEY="dummy_key"  # Not required for local deployment
VISION_BASE_URL="http://localhost:1234/v1/chat/completions"
```

--------------------------------

### Configure Environment Variables

Source: https://miromindai.github.io/MiroFlow/finsearchcomp

Required API keys for model access, web searching, and sandbox code execution.

```bash
# MiroThinker model access
OAI_MIROTHINKER_API_KEY="your-mirothinker-api-key"
OAI_MIROTHINKER_BASE_URL="http://localhost:61005/v1"

# For searching and web scraping
SERPER_API_KEY="xxx"
JINA_API_KEY="xxx"

# For code execution (E2B sandbox)
E2B_API_KEY="xxx"
```

--------------------------------

### Benchmark Preparation Script Contents

Source: https://miromindai.github.io/MiroFlow/download_datasets

The script handles access verification and executes individual download commands for each dataset.

```bash
#!/bin/bash
echo "Please grant access to these datasets:"
echo "- https://huggingface.co/datasets/gaia-benchmark/GAIA"
echo "- https://huggingface.co/datasets/cais/hle"
echo

read -p "Have you granted access? [Y/n]: " answer
answer=${answer:-Y}
if [[ ! $answer =~ ^[Yy] ]]; then
    echo "Please grant access to the datasets first"
    exit 1
fi
echo "Access confirmed"

# Comment out any unwanted datasets by adding # at the start of the line
uv run -m miroflow.utils.prepare_benchmark.main get gaia-val
uv run -m miroflow.utils.prepare_benchmark.main get gaia-val-text-only
uv run -m miroflow.utils.prepare_benchmark.main get frames-test
uv run -m miroflow.utils.prepare_benchmark.main get webwalkerqa
uv run -m miroflow.utils.prepare_benchmark.main get browsecomp-test
uv run -m miroflow.utils.prepare_benchmark.main get browsecomp-zh-test
uv run -m miroflow.utils.prepare_benchmark.main get hle
uv run -m miroflow.utils.prepare_benchmark.main get xbench-ds
uv run -m miroflow.utils.prepare_benchmark.main get futurex
```

--------------------------------

### Build Custom E2B Template

Source: https://miromindai.github.io/MiroFlow/e2b_advanced_features

Configures the access token and executes the build command to create a custom sandbox template from the Dockerfile.

```bash
# Set your E2B access token
E2B_ACCESS_TOKEN=${your-token}

# Build the template with docker build locally
e2b template build -c "/root/.jupyter/start-up.sh" -n "all_pip_apt_pkg" -d ./e2b.Dockerfile
```

--------------------------------

### Run tasks with different models

Source: https://miromindai.github.io/MiroFlow/quickstart

Executes the same task using different configuration files to switch the underlying LLM.

```bash
# With Claude
bash scripts/test_single_task.sh \
  --config config/agent_quickstart_claude.yaml \
  --task-question "What is the first country listed in the XLSX file that have names starting with Co?" \
  --file-path data/FSI-2023-DOWNLOAD.xlsx

# With MiroThinker
bash scripts/test_single_task.sh \
  --config config/agent_quickstart_mirothinker.yaml \
  --task-question "What is the first country listed in the XLSX file that have names starting with Co?" \
  --file-path data/FSI-2023-DOWNLOAD.xlsx
```

--------------------------------

### Customize task execution

Source: https://miromindai.github.io/MiroFlow/quickstart

Demonstrates running tasks with different files via shell script or direct Python execution.

```bash
# Analyze different files
bash scripts/test_single_task.sh \
  --config config/agent_quickstart.yaml \
  --task-question "Summarize the main findings in this document" \
  --file-path path/to/your/document.pdf

# Or run directly with Python
uv run python scripts/run_single_task.py \
  --config-path config/agent_quickstart.yaml \
  --task-question "What is the first country listed in the XLSX file that have names starting with Co?" \
  --file-path data/FSI-2023-DOWNLOAD.xlsx
```

--------------------------------

### Configure Environment Variables

Source: https://miromindai.github.io/MiroFlow/gaia_test

Required API keys and base URL settings for MiroThinker, search tools, and code execution environments.

```text
# MiroThinker model access
OAI_MIROTHINKER_API_KEY="your-mirothinker-api-key"
OAI_MIROTHINKER_BASE_URL="http://localhost:61005/v1"

# Search and web scraping capabilities
SERPER_API_KEY="your-serper-api-key"
JINA_API_KEY="your-jina-api-key"

# Code execution environment
E2B_API_KEY="your-e2b-api-key"
```

--------------------------------

### Configure environment variables

Source: https://miromindai.github.io/MiroFlow/quickstart

Required API keys for agent functionality, including LLM providers, search, and code execution.

```text
OPENAI_API_KEY=your_key_here          # For GPT-5
SERPER_API_KEY=your_key_here           # For web search
E2B_API_KEY=your_key_here              # For code sandbox
OAI_MIROTHINKER_API_KEY=your_key_here  # For MiroThinker
```

--------------------------------

### Configure Prompts with YAML and Jinja2

Source: https://miromindai.github.io/MiroFlow/core_concepts

Define agent prompts using YAML files with Jinja2 templating for dynamic content generation.

```yaml
template:
  initial_user_text:
    components:
      - task_description
      - task_guidance
      - file_input_prompt
    task_description: |
      {{ task_description }}
    file_input_prompt: |
      {% if file_input is defined and file_input is not none %}
      A {{ file_input.file_type }} file '{{ file_input.file_name }}'
      is associated with this task.
      {% endif %}
```

--------------------------------

### Review task logs

Source: https://miromindai.github.io/MiroFlow/contribute_benchmarks

Displays the first 50 lines of a specific task log file for inspection.

```bash
cat logs/your-benchmark/task_*_attempt_1.json | head -50
```

--------------------------------

### Implement MCP Server Logic

Source: https://miromindai.github.io/MiroFlow/contribute_tools

Create a new MCP server using FastMCP to define tool functionality and parameters.

```python
from fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("new-mcp-server")

@mcp.tool()
async def tool_name(param: str) -> str:
    """
    Explanation of the tool, its parameters, and return value.
    """
    tool_result = ...  # Your logic here
    return tool_result

if __name__ == "__main__":
    mcp.run(transport="stdio")
```

--------------------------------

### Execute Benchmark Script

Source: https://miromindai.github.io/MiroFlow/model_comparison

Run the provided shell script to execute the benchmark for the configured model.

```bash
bash scripts/benchmark/mirothinker/gaia-validation-165_mirothinker_8runs.sh
# (or adapt the script for your config)
```

--------------------------------

### Define a Skill with SKILL.md

Source: https://miromindai.github.io/MiroFlow/core_concepts

Skills use YAML frontmatter for metadata and markdown for instructions. Place these files in the miroflow/skill/skills directory for auto-discovery.

```markdown
---
name: simple_file_understanding
description: Understand and analyze CSV files. Use when the task
             involves reading, parsing, or answering questions
             about data in a CSV file.
---

# simple_file_understanding

## Instructions
When a task involves a CSV file, follow this workflow:
1. Use the `read_file` tool to load the file content.
2. Identify column headers, data types, and row count.
3. Answer the question based on the data.
```

--------------------------------

### Define a Skill with Markdown

Source: https://miromindai.github.io/MiroFlow/whats_new

Create a new agent skill by defining a SKILL.md file with YAML frontmatter for instructions and metadata.

```text
miroflow/skill/skills/simple_file_understanding/
└── SKILL.md
```

```markdown
---
name: simple_file_understanding
description: Understand and analyze CSV files.
---

# Instructions
1. Use `read_file` to load the CSV content.
2. Identify column headers, data types, and row count.
3. Answer the question based on the data.
```

--------------------------------

### Execute GAIA Benchmark Evaluation

Source: https://miromindai.github.io/MiroFlow/gaia_test

Command to run the evaluation script with a specific configuration file and output directory.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_gaia-validation-165_mirothinker.yaml \
  benchmark=gaia-test \
  output_dir="logs/gaia-test/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Standard Benchmark Configuration

Source: https://miromindai.github.io/MiroFlow/yaml_config

Configuration for running a GAIA validation benchmark with specific tools and processors.

```yaml
defaults:
  - benchmark: gaia-validation-165
  - override hydra/job_logging: none
  - _self_

entrypoint: main_agent
main_agent:
  name: main_agent
  type: IterativeAgentWithToolAndRollback
  max_consecutive_rollbacks: 5
  max_turns: 200

  llm:
    _base_: config/llm/base_mirothinker.yaml

  prompt: config/prompts/prompt_main_agent_benchmark.yaml

  tools:
    - config/tool/tool-code-sandbox.yaml
    - config/tool/tool-serper-search.yaml
    - config/tool/tool-jina-scrape.yaml

  tool_blacklist:
    - server: "tool-serper-search"
      tool: "sogou_search"

  input_processor:
    - ${file-content-preprocessor}
    - ${input-message-generator}
  output_processor:
    - ${output-summary}
    - ${output-boxed-extractor}
    - ${output-exceed-max-turn-summary}
```

--------------------------------

### Configure Audio MCP Server Environment Variables

Source: https://miromindai.github.io/MiroFlow/tool_audio_os

Set these variables in the tool-audio-os.yaml configuration file to define the Whisper model and API connection details.

```bash
# API for Open-Source Audio Transcription Tool (for benchmark testing)
WHISPER_MODEL_NAME="openai/whisper-large-v3-turbo"
WHISPER_API_KEY=your_whisper_key
WHISPER_BASE_URL="https://your_whisper_base_url/v1"
```

--------------------------------

### Run document analysis

Source: https://miromindai.github.io/MiroFlow/quickstart

Executes a single task using the specified configuration, question, and file path.

```bash
bash scripts/test_single_task.sh \
  --config config/agent_quickstart.yaml \
  --task-question "What is the first country listed in the XLSX file that have names starting with Co?" \
  --file-path data/FSI-2023-DOWNLOAD.xlsx
```

--------------------------------

### View Configuration Directory Structure

Source: https://miromindai.github.io/MiroFlow/yaml_config

Displays the standard directory layout for MiroFlow configuration files.

```text
config/
├── agent_*.yaml                      # Agent configurations (quickstart, web demo, etc.)
├── benchmark_*.yaml                  # Benchmark configurations
├── prompts/                          # Prompt classes (.py and .yaml)
├── llm/                              # LLM provider configurations
├── benchmark/                        # Benchmark dataset settings
└── tool/                             # Tool configurations
```

--------------------------------

### Run Benchmarks

Source: https://miromindai.github.io/MiroFlow/yaml_config

Executes predefined benchmark scripts for validation and testing.

```bash
# GAIA validation with MiroThinker (8 runs)
bash scripts/benchmark/mirothinker/gaia-validation-165_mirothinker_8runs.sh

# BrowseComp English with MiroThinker (3 runs)
bash scripts/benchmark/mirothinker/browsecomp-en_mirothinker_3runs.sh
```

--------------------------------

### Download Futurex-Online Dataset

Source: https://miromindai.github.io/MiroFlow/futurex

Use this command to download and process the dataset into a standardized JSONL format.

```bash
uv run -m miroflow.utils.prepare_benchmark.main get futurex
```

--------------------------------

### Manual Dataset Download

Source: https://miromindai.github.io/MiroFlow/gaia_validation_prerequisites

Download and extract the GAIA validation dataset directly from the repository.

```bash
cd data
wget https://huggingface.co/datasets/miromind-ai/MiroFlow-Benchmarks/resolve/main/gaia-val.zip
unzip gaia-val.zip
# Unzip passcode: pf4*
```

--------------------------------

### Set Environment Variables

Source: https://miromindai.github.io/MiroFlow/openrouter-claude-3.7-sonnet

Required environment variables for OpenRouter authentication and base URL configuration.

```bash
export OPENROUTER_API_KEY="your-openrouter-key"
export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"  # optional
```

--------------------------------

### Enable Skills in Agent Configuration

Source: https://miromindai.github.io/MiroFlow/core_concepts

Configure skill directories and enable Python-based skill execution in the agent's main configuration file.

```yaml
main_agent:
  skill:
    skill_dirs:
      - miroflow/skill/skills
    allow_python_skills: true
```

--------------------------------

### Download Execution Traces

Source: https://miromindai.github.io/MiroFlow/gaia_validation_claude37sonnet

Commands to download and extract the public execution traces for the gaia-validation dataset.

```bash
wget https://huggingface.co/datasets/miromind-ai/MiroFlow-Benchmarks/resolve/main/gaia_validation_miroflow_trace_public_20250825.zip
unzip gaia_validation_miroflow_trace_public_20250825.zip
# Unzip passcode: pf4*
```

--------------------------------

### Configure the Reading Tool

Source: https://miromindai.github.io/MiroFlow/tool_reading

Add the tool-reading tool to the agent configuration.

```yaml
main_agent:
  tool_config: 
    - tool-reading
```

--------------------------------

### Run BrowseComp-EN-200 Subset Evaluation

Source: https://miromindai.github.io/MiroFlow/browsecomp_en

Executes a 3-run evaluation on the 200-task subset.

```bash
bash scripts/benchmark/mirothinker/browsecomp-en-200_mirothinker_3runs.sh
```

--------------------------------

### Set Environment Variables

Source: https://miromindai.github.io/MiroFlow/contribute_llm_clients

Export the necessary API credentials and base URL as environment variables for the provider client to access.

```bash
export YOUR_API_KEY="your-key"
export YOUR_BASE_URL="https://api.yourprovider.com/v1"  # optional if using default
```

--------------------------------

### Test with Limited Tasks

Source: https://miromindai.github.io/MiroFlow/finsearchcomp

Runs the benchmark on a subset of tasks by setting the max_tasks parameter.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_gaia-validation-165_mirothinker.yaml \
  benchmark=finsearchcomp \
  benchmark.execution.max_tasks=5 \
  output_dir="logs/finsearchcomp/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Run HLE Evaluation

Source: https://miromindai.github.io/MiroFlow/hle

Executes the benchmark evaluation using the specified configuration and output directory.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_hle_mirothinker.yaml \
  benchmark.execution.max_concurrent=30 \
  output_dir="logs/hle/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Configure Agent for Audio Tools

Source: https://miromindai.github.io/MiroFlow/tool_audio

Add tool-audio to the agent configuration to enable audio processing capabilities.

```yaml
main_agent:
  tool_config: 
    - tool-audio
```

--------------------------------

### Run HLE Text-Only Evaluation

Source: https://miromindai.github.io/MiroFlow/hle_text_only

Executes the benchmark with specified configuration and output directory.

```bash
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_hle-text-only_mirothinker.yaml \
  benchmark.execution.max_concurrent=30 \
  output_dir="logs/hle-text-only/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Review Benchmark Results

Source: https://miromindai.github.io/MiroFlow/hle_text_only

Commands to view accuracy summaries and check progress of the evaluation.

```bash
# View accuracy summary
cat logs/hle-text-only/*/benchmark_results_pass_at_1_accuracy.txt

# Check progress
uv run utils/check_progress_hle-text-only.py $PATH_TO_LOG
```

--------------------------------

### google_search(q: str, gl: str = "us", hl: str = "en", location: str = None, num: int = 10, tbs: str = None, page: int = 1)

Source: https://miromindai.github.io/MiroFlow/tool_searching_serper

Performs a Google search using the Serper API with support for location, language, and time-based filtering.

```APIDOC
## google_search

### Description
Perform Google searches via Serper API.

### Parameters
- **q** (str) - Required - Search query
- **gl** (str) - Optional - Country code (e.g., 'us', 'uk', 'cn'). Default: 'us'
- **hl** (str) - Optional - Language (e.g., 'en', 'zh', 'es'). Default: 'en'
- **location** (str) - Optional - City location (e.g., 'San Francisco, California, United States')
- **num** (int) - Optional - Number of results. Default: 10
- **tbs** (str) - Optional - Time filter ('qdr:h'=hour, 'qdr:d'=day, 'qdr:w'=week, 'qdr:m'=month, 'qdr:y'=year)
- **page** (int) - Optional - Page number. Default: 1

### Returns
- **str** - JSON formatted search results

### Example
```python
# Basic search
results = await google_search("artificial intelligence")

# With filters
results = await google_search("latest news", tbs="qdr:d", num=20)
```
```

--------------------------------

### Download HLE Dataset

Source: https://miromindai.github.io/MiroFlow/hle

Downloads the HLE dataset from HuggingFace and saves images to the local data directory.

```bash
uv run -m miroflow.utils.prepare_benchmark.main get hle
```

--------------------------------

### Monitor Evaluation Progress

Source: https://miromindai.github.io/MiroFlow/gaia_validation_prerequisites

Track real-time progress for specific GAIA validation benchmarks using the provided utility scripts.

```bash
uv run utils/check_progress_gaia-validation-165.py $PATH_TO_LOG

# Or for GAIA-Validation-Text-103
uv run utils/check_progress_gaia-validation-text-103.py $PATH_TO_LOG
```

--------------------------------

### Download Specific Dataset

Source: https://miromindai.github.io/MiroFlow/download_datasets

Run an individual command to download a specific dataset instead of the full suite.

```bash
# Download a single dataset
uv run -m miroflow.utils.prepare_benchmark.main get gaia-val-text-only

# Or edit the script and comment out unwanted lines
```

--------------------------------

### Deploy MiroThinker-32B with SGLang

Source: https://miromindai.github.io/MiroFlow/mirothinker

Launches the SGLang server for the MiroThinker model. Adjust the tensor parallelism (--tp) parameter based on available GPU resources.

```bash
python3 -m sglang.launch_server \
    --model-path miromind-ai/MiroThinker-32B-DPO-v0.2 \
    --tp 8 \
    --dp 1 \
    --host 0.0.0.0 \
    --port 61005 \
    --trust-remote-code \
    --chat-template qwen3_nonthinking.jinja
```

--------------------------------

### Configure Agent for New Provider

Source: https://miromindai.github.io/MiroFlow/contribute_llm_clients

Specify the provider class and model details in the agent configuration file using OmegaConf environment variable interpolation.

```yaml
main_agent:
  llm: 
    provider_class: "YourProviderClient"
    model_name: "your-model"
    your_api_key: "${oc.env:YOUR_API_KEY,???}"
    your_base_url: "${oc.env:YOUR_BASE_URL,https://api.yourprovider.com/v1}"
```

--------------------------------

### Execute Benchmark Command

Source: https://miromindai.github.io/MiroFlow/claude-3.7-sonnet

Command to run the agent using the Claude 3.7 Sonnet configuration against the common benchmark dataset.

```bash
# Run with Claude 3.7 Sonnet (Anthropic SDK) on example dataset
uv run main.py common-benchmark --config_file_name=agent_llm_claude37sonnet_anthropic output_dir="logs/test"
```

--------------------------------

### Define Tool Configuration

Source: https://miromindai.github.io/MiroFlow/contribute_tools

Specify the tool command and arguments in a YAML configuration file.

```yaml
name: "new-tool-name"
tool_command: "python"
args:
  - "-m"
  - "miroflow.tool.mcp_servers.new-mcp-server"  # Match the server file created above
```

--------------------------------

### Run with Custom Concurrency

Source: https://miromindai.github.io/MiroFlow/webwalkerqa

Executes the benchmark with a specific number of concurrent tasks.

```bash
# Run with 10 concurrent tasks
uv run miroflow/benchmark/run_benchmark.py \
  --config-path config/benchmark_webwalkerqa_mirothinker.yaml \
  benchmark.execution.max_concurrent=10 \
  output_dir="logs/webwalkerqa/$(date +"%Y%m%d_%H%M")"
```

--------------------------------

### Update Benchmark Configuration

Source: https://miromindai.github.io/MiroFlow/model_comparison

Modify the main agent configuration in a benchmark YAML file to point to your specific model and client.

```yaml
# Copy any existing benchmark config, e.g.:
# config/benchmark_gaia-validation-165_mirothinker.yaml

# Change only these two lines:
main_agent:
  llm:
    provider_class: OpenAIClient       # Your client
    model_name: your-model-name        # Your model
```

--------------------------------

### reasoning(question: str)

Source: https://miromindai.github.io/MiroFlow/tool_reasoning

Performs step-by-step reasoning, analysis, and planning over a text-only input. This tool is specialized for complex thinking tasks.

```APIDOC
## reasoning(question: str)

### Description
Perform step-by-step reasoning, analysis, and planning over a text-only input. This tool is specialized for complex thinking tasks and does not fetch external data.

### Parameters
- **question** (str) - Required - A detailed, complex question or problem statement that includes all necessary information.

### Returns
- **str** - A structured, step-by-step reasoned answer.
```

--------------------------------

### Download Dataset via Script

Source: https://miromindai.github.io/MiroFlow/gaia_validation_prerequisites

Use the MiroFlow utility script to download the GAIA validation dataset.

```bash
uv run -m miroflow.utils.prepare_benchmark.main get gaia-val
```

--------------------------------

### Set OpenRouter API Key

Source: https://miromindai.github.io/MiroFlow/deepseek

Configure the required environment variable for OpenRouter authentication.

```bash
export OPENROUTER_API_KEY="your-key"
```