ReasFlow

Assisting Reasoning-Centric Scientific Discovery in Applied Mathematics
via a Knowledge-Based Multi-Agent System

An end-to-end agent system that supports literature survey, algorithm design, theorem proving,
numerical experiments, and manuscript preparation in a shared research workspace.

Paper  ·  Blog  ·  Platform  ·  Architecture  ·  Quick Start  ·  Results  ·  Citation

---

Overview

Recent advances in Large Language Models have fueled autonomous agents that tackle complex scientific tasks, yet existing systems remain focused on empirically driven domains with quantitative benchmarks — leaving theory-driven discovery in applied mathematics largely underexplored.

ReasFlow supports a collaborative paradigm in which the human expert acts as Principal Investigator and specialist agents carry out research tasks for expert inspection and iteration. Taking distributed optimization as a concrete testbed, it brings literature survey, algorithm design, theorem development, numerical experimentation, and manuscript preparation into a shared workflow.

Under the hood, ReasFlow is built on the Agent Client Protocol (ACP) and plays a dual role:

• As an ACP Agent — exposes itself to editors (e.g. Zed) over stdio.
• As an ACP Client — spawns and manages bundled specialist sub-agents, forwards their messages, and tags their updates for source identification.

ReasFlow is publicly accessible via the ReasLab platform, providing a collaborative workspace for AI-assisted theoretical research.

---

✨ Core Innovations

	Innovation	What it does
🧠	Reasoning-Centric Discovery	Formulates candidate assumptions and theoretical statements, then develops derivations for expert inspection and iteration.
📁	End-to-End Research Workspace	Unifies survey, algorithm design, proving, experiments, and writing in one shared workspace. Every artifact is a file the user can inspect, modify, and iterate on at any time.
✅	Internal Verification Loops	Verification steps cover proof coherence, numerical consistency, and manuscript compilation, helping surface low-level mistakes before human inspection.
📇	Automated Knowledge Cards	A dedicated extraction and retrieval mechanism distills both declarative facts and tacit procedural heuristics from the literature, proactively surfacing relevant proof techniques the model would otherwise overlook.

---

🏗 Architecture

_{The ReasFlow multi-agent workflow. MetaAgent dispatches tasks across specialist agents that share a common workspace; SurveyAgent, AlgorithmAgent, and ProverAgent use task-specific knowledge cards.}

• reasflow/ — the MetaAgent coordinator: ACP server, session lifecycle, passthrough routing, sub-agent process management, update tagging, context compaction, and slash-command handling.
• agents/ — the bundled specialist sub-agents, each launched as its own ACP process and invoked by the coordinator as a tool.

Bundled Sub-Agents

Each sub-agent is a bundled implementation with its own ACP entry point and specialized prompt/tool set.

Agent	Directory	Role
SurveyAgent	agents/survey/	Retrieves and synthesizes related literature into a survey section.
AlgorithmAgent	agents/alg_exp/	Designs the algorithm (pseudocode, assumptions, design rationale).
ProverAgent	agents/prover/	Derives theorems and proofs; produces a formal theoretical report.
ExperimentAgent	agents/alg_exp/	Implements and runs real experiments; produces an experiment report.
IntroductionAgent	agents/intro/	Drafts the introduction from available survey, method, theory, and experiment materials.
WritingAgent	agents/paper/	Assembles and revises the available sections into an integrated LaTeX manuscript.

AlgorithmAgent and ExperimentAgent share the agents/alg_exp/ package and are launched in different modes.

---

📊 Results at a Glance

In the controlled full-paper evaluation for Paper 1, all systems received the same initial prompt, including the core research idea and seminal references. Under the nine-dimension LLM-review rubric, ReasFlow received the highest average score among the nine evaluated systems.

AI Agent	Reviewer: GPT-5.1	Reviewer: GPT-5.4	Reviewer: Gemini-3-Pro	Average
ChatGPT (GPT-5.3)	51.7	32.2	29.8	37.9
ChatGPT Pro (GPT-5.4-Pro)	62.4	44.5	41.9	49.6
Gemini-3.1-Pro	51.5	31.4	35.1	39.3
Claude Pro (Opus 4.6)	64.4	32.9	61.4	52.9
CycleResearcher-ML-12B	34.6	19.1	10.1	21.2
DeepScientist (GPT-5.4)	71.9	56.6	43.5	57.3
AI Scientist-v2 (GPT-5.4)	60.6	34.7	29.6	41.6
ARIS (GPT-5.4)	59.3	52.9	38.6	50.3
ReasFlow (GPT-5.4)	80.5	65.6	87.6	77.9

_{Full-paper evaluation scores across three LLM reviewers. Bold indicates best. See the paper and released detailed reviews for the rubric and results.}

_{Full-paper evaluation by dimension. Scores are averaged across the three reviewer backends; higher is better.}

---

🚀 Quick Start

Installation

git clone https://github.com/reaslab/ReasFlow.git
cd ReasFlow
uv sync
cp .env.example .env   # then fill in credentials

Credentials may be provided in .env or via the environment. ACP session metadata (passed by the editor) takes precedence over local defaults.

Running

Start the MetaAgent coordinator (waits for an ACP connection on stdin/stdout):

uv run reasflow
# or, with stderr logging (stdout is reserved for ACP JSON-RPC):
uv run python -m reasflow 2>stderr.log

Editor Integration (Zed / ACP)

Add ReasFlow as a custom agent server in your Zed settings:

{
  "agent_servers": {
    "reasflow": {
      "type": "custom",
      "command": "uv",
      "args": ["run", "--project", "/path/to/reasflow", "python", "-m", "reasflow"],
      "env": {
        "REASFLOW_CONFIG": "/path/to/reasflow/config/reasflow.settings.json"
      }
    }
  }
}

---

💬 Usage

Coordinator mode — the MetaAgent routes work across sub-agents:

Analyze the convergence of FedAvg and draft a proof, then run experiments.

Passthrough mode — talk to a specific sub-agent directly:

@survey  find related work on federated optimization
@prover  prove this lemma
@paper   assemble the draft
@meta    # return to coordinator mode

---

📁 Repository Structure

Path	What it is
reasflow/	MetaAgent coordinator (ACP server + sub-agent client logic).
agents/	Bundled specialist sub-agents (survey, alg_exp, prover, intro, paper).
config/	Default runtime settings (reasflow.settings.json) and experiment configs.
benchmarks/	Benchmark tasks, evaluation code, and deterministic result checks.
results/	Released experiment results and paper-generation outputs.
tests/	Unit and integration tests.
scripts/	Smoke tests and helper scripts.
pyproject.toml	Python project + tooling config.

---

🔬 Evaluation & Reproducibility

benchmarks/ contains evaluation and deterministic verification code. The records, generated papers, reviewer JSON, and table sources used by the paper are released under results/. Together, these directories support reproduction of the reported table calculations and execution of new evaluations.

Module	Reproduces	Highlights
alg_exp_eval/	Tables 3 and 5	AlgorithmAgent and ExperimentAgent evaluations across 20 MLR-Bench tasks and 15 OR-Bench tasks, with 420 raw records and offline table verification.
writing_eval/	Table 7	Four-phase WritingAgent evaluator with released results for 11 systems.
full_paper_eval/	Table 1	Nine-dimension full-paper reviewer and deterministic verification for 9 systems × 3 reviewers.
prover_eval/	Table 4	Five-dimension ProofReviewAgent plus 3-reviewer verification for 11 proof reports.
survey_eval/	Table 2	SurveyAgent generation and evaluation across three paper tasks.
intro_eval/	Table 6	IntroductionAgent evaluation across 3 papers × 3 reviewers.

The unified CLI:

uv run python -m benchmarks smoke-test          # environment check
uv run python -m benchmarks alg-exp verify      # Algorithm/Experiment results
uv run python -m benchmarks prover verify       # Prover results
uv run python -m benchmarks writing verify      # WritingAgent results
uv run python -m benchmarks full-paper verify   # full-paper results

Start with benchmarks/README.md; each evaluation package also documents its own scope and dependencies.

Case Studies

results/ holds the end-to-end paper-generation outputs the paper analyzes in depth.

Directory	Contents
Paper01_SFedAvg/ … Paper05_RF-EXTRA/	ReasFlow-generated case-study workspaces with the available per-agent outputs. All contain survey/, prover/, Alg_Exp/, and writing/; Paper01–03 also contain complete intro/ outputs. Final manuscripts are under writing/final_report/.
prover_experiments/	11 proof-evaluation PDFs and 3 reviewer score JSON files used in Table 4.
writing_experiments/	WritingAgent inputs, 11 final outputs, canonical four-phase reports, and score snapshot.
system_level_full_papers/	9 full-paper PDFs (ChatGPT, Claude Pro, Gemini, DeepScientist, ARIS, ReasFlow, …) scored in Table 1.

---

⚙️ Configuration

Variable	Purpose
OPENAI_API_KEY / OPENAI_BASE_URL	Default model backend.
ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL	Anthropic backend (when used).
SEMANTIC_SCHOLAR_API_KEY	Literature retrieval (SurveyAgent).
REASFLOW_CONFIG	Path to settings JSON (default config/reasflow.settings.json).
REASFLOW_PROMPT	Path to the coordinator system prompt.
REASFLOW_WORKSPACE	Working directory for file operations.
REASFLOW_LOG_DIR	Log directory (default <root>/logs).

---

🧪 Testing

uv run pytest tests/ -v

Offline focused smoke test:

uv run python scripts/smoke_acp_meta_routing.py --case no-meta-uses-default

Running the full routing smoke suite requires OPENAI_API_KEY and makes real model calls.

---

🔒 Safety

• The coordinator can execute local shell commands via sub-agents.
• Run it only in trusted workspaces with trusted prompts.
• File tools are sandboxed to the configured workspace by default.
• Set REASFLOW_ALLOW_OUTSIDE_WORKSPACE=1 only if you intentionally need broader file access.

---

📖 Citation

If you use ReasFlow in your research, please cite our paper:

@misc{he2026reasflow,
  title         = {ReasFlow: Assisting Reasoning-Centric Scientific Discovery in Applied
                   Mathematics via a Knowledge-Based Multi-Agent System},
  author        = {Yutong He and Daibo Li and Guohong Li and Jiahe Geng and
                   Zhengyang Huang and Can Ren and Zekun Zhang and Yifan Liu and
                   Shuchen Zhu and Hengrui Zhang and Boao Kong and Ming Sun and
                   Shu Li and Chenyi Li and Jiang Hu and Kun Yuan and Zaiwen Wen and
                   Pingwen Zhang},
  year          = {2026},
  eprint        = {2607.14178},
  archivePrefix = {arXiv},
  primaryClass  = {cs.AI},
  url           = {https://arxiv.org/abs/2607.14178}
}

Authors: Yutong He^1,*, Daibo Li^1,*, Guohong Li^1,*, Jiahe Geng^1,*, Zhengyang Huang^1,*, Can Ren^1,*, Zekun Zhang^2,†, Yifan Liu^3,†, Shuchen Zhu¹, Hengrui Zhang¹, Boao Kong¹, Ming Sun¹, Shu Li⁴, Chenyi Li¹, Jiang Hu⁴, Kun Yuan^1,¶, Zaiwen Wen^1,¶, Pingwen Zhang^5,¶.

¹ Peking University · ² University of Electronic Science and Technology of China · ³ Beijing Normal University · ⁴ Tsinghua University · ⁵ Wuhan University

^* Equal contribution · ^† Work done while interning at Peking University · ^¶ Corresponding author

See CITATION.cff for machine-readable metadata.

---

📝 License

ReasFlow's original code and local modifications are released under the MIT License — see LICENSE. Vendored code, benchmark materials, and data artifacts may have separate terms; see THIRD_PARTY_NOTICES.md.