luxiongyi/amas

🐝 GPTSwarm is a graph-based framework for LLM-based agents, providing two high-level features:

It lets you build LLM-based agents from graphs.
It enables the customized and automatic self-organization of agent swarms with self-improvement capabilities.

Unofficial AMAS Reproduction

This fork includes an unofficial AMAS-inspired reproduction built on top of GPTSwarm. It is designed for learning and reproducible experimentation, not as the official AMAS implementation.

AMAS asks a sample-level question: after GPTSwarm has produced several strong candidate communication graphs, which graph should the multi-agent system use for this specific input? The implementation in this repository adds:

Component	Location
Candidate graph dataclasses and JSON serialization	`swarm/amas/types.py`, `swarm/amas/graph_io.py`
Candidate graph scoring and ranking loss	`swarm/amas/scoring.py`, `swarm/amas/ranking.py`
Task adapters, paper graph template, and paper runtime	`swarm/amas/adapters/`, `swarm/amas/graphs/`
Graph designer training data and lightweight/LoRA-smoke designers	`swarm/amas/designer_dataset.py`, `swarm/amas/designer/`
MMLU AMAS-MVP pipeline	`swarm/amas/pipeline.py`, `experiments/run_amas_mmlu.py`
Paper-code reproduction CLI, matrix, and reports	`experiments/run_amas.py`, `experiments/run_amas_matrix.py`, `experiments/run_amas_report.py`

Current reproduction status:

Implemented: AMAS-MVP on MMLU plus a paper-code path with multi-task adapters, a 12-node ToT + Reflection template, paper candidate generation/scoring, paper_dynamic_mock, prompt baselines, matrix runs, and aggregate reports.
Reproduced locally: debug-size mock runs for Game24/MMLU-style paths; DeepSeek debug runs require a local .env and should be treated as small smoke tests.
Optional: LoRA designer has a stable config/manifest path and smoke_backend=linear; real HF/PEFT LoRA training is intentionally optional.

Quick smoke test:

$env:PYTHONPATH='.'; .\.conda\gptswarm-repro\python.exe experiments\run_amas_mmlu.py --debug --model_name=mock --designer=linear

Paper-code smoke test:

$env:PYTHONPATH='.'; .\.conda\gptswarm-repro\python.exe experiments\run_amas.py --config configs\amas\debug_game24_paper_dynamic_mock.yaml --run-dir runs\amas_debug\paper_dynamic_game24

Aggregate mock matrix:

$env:PYTHONPATH='.'; .\.conda\gptswarm-repro\python.exe experiments\run_amas_matrix.py --config configs\amas\matrix_paper_code_repro_mock.yaml --runs-dir runs\amas_matrix_debug --output-dir reports\amas_matrix_debug
$env:PYTHONPATH='.'; .\.conda\gptswarm-repro\python.exe experiments\run_amas_report.py --runs-dir runs\amas_matrix_debug --output-dir reports\amas_debug

DeepSeek debug run:

$env:PYTHONPATH='.'; .\.conda\gptswarm-repro\python.exe experiments\run_amas_mmlu.py --debug --model_name=deepseek-v4-flash --designer=linear

Useful AMAS docs:

docs/AMAS_OVERVIEW.md
docs/amas_paper_reading_and_reproduction_report_zh.md
docs/amas_full_code_reproduction_spec_zh.md
docs/AMAS_FULL_REPRODUCTION_GUIDE.md
docs/AMAS_METHOD_MAPPING.md
docs/REPRODUCTION_GUIDE.md
docs/API_DESIGN.md
docs/LIMITATIONS.md
docs/COST_GUIDE.md
examples/amas_mmlu_debug/README.md

About GPTSwarm

At a granular level, GPTSwarm is a library that includes the following components:

Module	Description
swarm.environment	Domain-specific operations, agents, tools, and tasks
swarm.graph	Graph-related functions for creating and executing agent graphs and swarm composite graphs
swarm.llm	Interface for selecting LLM backends and calculating their operational costs
swarm.memory	Index-based memory
swarm.optimizer	Optimization algorithms designed to enhance agent performance and overall swarm efficiency

Visualizations of the graphs

News

😎 [10/12] Respect 🐝 OpenAI’s Swarm, but 🐝 GPTSwarm is the better option if consider the 🐝Swarm Intelligence🐝.
🔥 [08/07] Mingchen attended an invited seminar with Shanghai AI Lab.
🔥 [07/25] Louis and Francesco gave the oral presentation in ICML 2024.
🔥 [07/17] Mingchen introduced GPTSwarm to Meta.
🔥 [07/05] Mingchen gave an invited talk to WAIC.
🔥 [06/21] Mingchen gave an invited talk to IA-CAS.
🔥 [06/20] Dmitrii gave an invited talk to Sberbank.
🔥 [06/03] SDAIA invited GPTSwarm team (Wenyi, Francesco, Dmitrii) for a 5 hour seminar.
🔥 [06/02] GPTSwarm has been selected as Oral Presentation (top 1.5%, 144 in 9,473) by ICML2024! Congratulation!
🔥 [05/01] GPTSwarm has been accepted by ICML2024.
🔥 [04/18] Mingchen gave the invited talk to ByteDance.
🔥 [03/20] Mingchen gave the invited talk to HUAWEI.
🔥 [03/13] MITTR China Exclusive Interview with Mingchen.
🔥 [03/01] GPTSwarm can be installed via pip now: pip install gptswarm
🔥 [02/27] Our academic paper: Language Agents as Optimizable Graphs is released.

Edge optimization example

Here is the edge optimization process that updates edge probabilities toward improvement of the benchmark score. Notice that within an agent, the edges are fixed, whereas the inter-agent connections are getting optimized towards either edge pruning (value 0, blue) or creation (value 1, red).

Quickstart

Clone the repo

git clone https://github.com/metauto-ai/GPTSwarm.git
cd GPTSwarm/

Install packages

conda create -n swarm python=3.10
conda activate swarm
pip install poetry
poetry install

You should add API keys in .env.template and change its name to .env

OPENAI_API_KEY="" # for OpenAI LLM backend
BING_API_KEY="" # for Bing Web Search
GOOGLE_API_KEY="" # for Google Web Search
SEARCHAPI_API_KEY="" # for SearchAPI  Web Search

Selecting the Search Engine

The system will automatically select the appropriate search engine based on the following priority:

Bing API: If BING_API_KEY is provided
Search API: If SEARCHAPI_API_KEY is provided
Google API: If GOOGLE_API_KEY is provided

Getting started with GPTSwarm is easy. Quickly run a predefined swarm

from swarm.graph.swarm import Swarm

swarm = Swarm(["IO", "IO", "IO"], "gaia")
task = "What is the capital of Jordan?"
inputs = {"task": task}
answer = await swarm.arun(inputs)

or make use of tools, such as the file analyzer

from swarm.graph.swarm import Swarm
swarm = Swarm(["IO", "TOT"], "gaia")
task = "Tell me more about this image and summarize it in 3 sentences."
files = ["./datasets/demos/js.png"]
inputs = {"task": task, "files": files}
danswer = swarm.run(inputs)

Check out the minimal Swarm example in Colab here: .

See how to create a custom Agent and run a Swarm with it here: .

Here is a Youtube video on how to run the demo notebooks:

🔥🔥🔥 See our experiments for more advanced use of our framework.

Class diagram

Example of the Swarm

Running with a local LLM

We support local LM inference via LM Studio. Download their desktop app for Mac or Windows, choose a model from the Huggingface repository and start the server. Use model_name='lmstudio' in GPTSwarm code to run with the local LLM.

Contributors

Mingchen Zhuge (PhD Student@KAUST; Project Initiator)
Wenyi Wang (PhD Student @ KAUST; Initial Participant)
Dmitrii Khizbullin (Research Engineer Lead @ KAUST; Project Engineer Lead)
Louis Kirsch (PhD Student @ IDSIA)
Francesco Faccio (PostDoc@IDSIA; Visiting Researcher@KAUST)
Jürgen Schmidhuber (Director @ KAUST AI Initiative; Scientific Director @ IDSIA)
William FH (Engineering @ LangChain)
Lukas Vierling (BS Student @ RWTH & HKUST)
Sandro Hanea (Senior SDE @ Microsoft)

Please read our developer document if you are interested in contributing.

Citation

Please cite our paper if you find the library useful or interesting.

@inproceedings{zhugegptswarm,
  title={GPTSwarm: Language Agents as Optimizable Graphs},
  author={Zhuge, Mingchen and Wang, Wenyi and Kirsch, Louis and Faccio, Francesco and Khizbullin, Dmitrii and Schmidhuber, J{\"u}rgen},
  booktitle={Forty-first International Conference on Machine Learning}
}

If you use the AMAS-inspired reproduction, also cite the AMAS paper:

@inproceedings{leong2025amas,
  title={AMAS: Adaptively Determining Communication Topology for LLM-based Multi-Agent System},
  author={Leong, Hui Yi and Li, Yuheng and Wu, Yuqing and Ouyang, Wenwen and Zhu, Wei and Gao, Jiechao and Han, Wei},
  booktitle={Proceedings of the 2025 Conference on Empirical Methods in Natural Language Processing: Industry Track},
  year={2025}
}