RecursiveMAS Multi-Agent Framework

RecursiveMAS is a multi-agent framework that scales agent collaboration through latent-space recursion. Instead of treating LLM agents as isolated modules, it treats the entire multi-agent system (MAS) as a unified recursive computation.

Key components include:

• Heterogeneous Agents: Different LLM agents connected via RecursiveLink modules.
• RecursiveLink: Lightweight modules that allow agents to exchange, refine, and evolve latent states across recursion rounds.
• Inner-Outer Loop Training: A progressive co-optimization paradigm where the inner loop provides a model-level warm start for individual agents, and the outer loop trains the RecursiveLink across agents at the system level.

It supports several collaboration patterns: Sequential, Mixture, Distillation, and Deliberation.

RecursiveMAS training follows a two-phase approach to optimize agent collaboration through recursion:

1. Inner-Loop Training: Performed using train/train_inner.py. This phase trains each agent's role-specific inner RecursiveLink. This involves a frozen base model combined with a small ln_res_adapter. This step is run once per agent role.

2. Outer-Loop Training: Performed using train/train_outer.py. This phase connects all agents and trains the outer RecursiveLink between them. It loads the inner adapters from the first stage and keeps them frozen. Only the outer RecursiveLink modules are optimized.

Note on Gradients: During outer-loop training, gradients are allowed to pass through the frozen inner adapters, enabling the outer links to be trained across multiple recursion rounds.

RecursiveMAS implements different collaboration styles, each requiring specific model roles via --ckpt_override:

Sequential-Style

Roles: planner, critic, solver, outer.

Distillation-Style

Roles: expert, learner, outer.

Mixture-Style

Roles: math, code, science, summarizer, outer.

Deliberation-Style

Roles: reflector, toolcaller, outer. Requires --tavily_keys_file for search integration.

# Example: Mixture-Style
python inference/run.py \
  --style mixture \
  --dataset math500 \
  --device cuda \
  --ckpt_override math=train/ckpts/mixture/math_expert \
  --ckpt_override code=train/ckpts/mixture/code_expert \
  --ckpt_override science=train/ckpts/mixture/science_expert \
  --ckpt_override summarizer=train/ckpts/mixture/summarizer \
  --ckpt_override outer=train/ckpts/mixture/outer

Use inference/run.py to evaluate either a released reference system or a locally trained, task-specific configuration.

When evaluating, you can use the --ckpt_override flag multiple times to map specific agent roles (e.g., planner, critic, solver, outer) to their respective checkpoint directories.

# Evaluate Sequential Light Style RecursiveMAS on Math500
python inference/run.py \
  --style sequential_light \
  --dataset math500 \
  --device cuda \
  --ckpt_override planner=train/ckpts/seq_light/planner_math \
  --ckpt_override critic=train/ckpts/seq_light/refiner_math \
  --ckpt_override solver=train/ckpts/seq_light/solver_math \
  --ckpt_override outer=train/ckpts/seq_light/outer_math

You can use custom offline training data by placing JSON files in the ./train/data directory.

Each JSON file must follow this structure:

{
  "data": [
    {
      "question": "...",
      "answer": "..."
    }
  ]
}

To load local data, use the following flags in your training command:

• --dataset_name: The path to your local JSON file.
• --dataset_json_field: The name of the JSON key containing the data array (e.g., data).

Note: The --dataset_json_field flag should only be used for offline local data loading; it can be ignored when using Hugging Face datasets.

--dataset_name train/data/Sequential-Math.json \
--dataset_json_field data

Inner-Loop Training is the first phase of the RecursiveMAS training pipeline. It involves training each agent's role-specific inner RecursiveLink, which consists of a frozen base model and a small ln_res_adapter.

Use train/train_inner.py to perform this step. You must specify the model path, the MAS design (e.g., sequential), the specific agent role (e.g., planner), the task (e.g., math), and the corresponding dataset.

python train/train_inner.py \
  --model_name_or_path Qwen/Qwen3-1.7B \
  --mas_design sequential \
  --mas_role planner \
  --mas_task math \
  --dataset_name RecursiveMAS/Sequential-Math \
  --save_dir train/ckpts/seq_light/planner_math

RecursiveMAS training data is hosted on Hugging Face as row-format datasets with a train split. It is recommended to use these datasets directly whenever possible. To use a Hugging Face dataset, pass its name to the --dataset_name flag in the training command.

python train/train_inner.py \
  --dataset_name RecursiveMAS/Sequential-Math \
  ...

To set up RecursiveMAS, create a Python 3.10 environment using Conda and install the required dependencies from the repository root.

1. Create and activate environment

conda create -n recursivemas python=3.10 -y
conda activate recursivemas

2. Install dependencies

pip install -r requirements.txt