Setup

# API keys, put these into .env file
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
GEMINI_API_KEY=...

# Install things
sudo dnf install -y python3.12-devel
sudo dnf install -y graphviz graphviz-devel cmake ninja-build bzip2-devel zlib-devel ncurses-devel libffi-devel

# Create virtual environment
python3.12 -m venv venv_nat
source venv_nat/bin/activate
pip install -r requirements.txt
pip install -r requirements_dev.txt
# To build the docker container
docker build --network=host -t hyperagents .

# Setup initial agents
bash ./setup_initial.sh

Running HyperAgents

# See the script for args, and baseline selections
python generate_loop.py --domains <domain>

By default, outputs will be saved in outputs/ directory.

File Structure

• agent/ code for using foundation models
• analysis/ scripts used for plotting and analysis
• domains/ code for each domain
• utils/ common code used in the repo
• run_meta_agent.py script to help run the meta agent and get the diffs
• meta_agent.py main implementation of the meta agent
• task_agent.py main implementation of the task agent
• generate_loop.py entry point for running the algorithm

Logs from Experiments

The experiment logs can be downloaded here: https://drive.google.com/drive/folders/164fKQWgLM18foOzSnpv0F_I3TNpX8u8-?usp=sharing

Safety Consideration

[!WARNING]
This repository involves executing untrusted, model-generated code. We strongly advise users to be aware of the associated safety risks. While it is highly unlikely that such code will perform overtly malicious actions under our current settings and with the models we use, it may still behave destructively due to limitations in model capability or alignment. By using this repository, you acknowledge and accept these risks.

Citing

If you find this project useful, please consider citing:

@misc{zhang2026hyperagents,
      title={Hyperagents}, 
      author={Jenny Zhang and Bingchen Zhao and Wannan Yang and Jakob Foerster and Jeff Clune and Minqi Jiang and Sam Devlin and Tatiana Shavrina},
      year={2026},
      eprint={2603.19461},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2603.19461}, 
}