HyperAgents完整复现实验教程：从论文arXiv到本地跑通全量自进化循环

【免费下载链接】HyperAgentsSelf-referential self-improving agents that can optimize for any computable task项目地址: https://gitcode.com/gh_mirrors/hy/HyperAgents

HyperAgents是一个自指自改进智能体（Self-referential Self-improving Agents）框架，源自论文 arXiv:2603.19461，能让 AI 智能体针对任何可计算任务持续自我优化。本教程带你从安装依赖、初始化智能体，到用一条命令跑通完整的自进化循环（Self-improvement Loop），并解读每一代进化产生的输出与演化曲线，帮助新手快速复现 HyperAgents 论文实验。

一、30秒读懂 HyperAgents 自进化循环

HyperAgents 的核心是"两个智能体 + 一个档案库"：

每一代循环做四件事：选父代 → 运行 meta agent 修改代码 → 在基准上评测 → 更新档案并绘图。meta agent 被要求"修改代码库的任意部分"（见 meta_agent.py 的指令），实现真正的自指自我改进。

二、复现前准备：环境与依赖一键安装

复现 HyperAgents 需要 Python 3.12 和 Docker，官方安装步骤如下：

# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/hy/HyperAgents cd HyperAgents # 2. 系统依赖（Linux dnf 环境） 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 # 3. 虚拟环境 python3.12 -m venv venv_nat source venv_nat/bin/activate pip install -r requirements.txt pip install -r requirements_dev.txt

💡 API Key 需放入.env文件，包含OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY。模型配置集中在 agent/llm.py，默认 meta agent 使用 Claude Sonnet 4.5。

三、构建 Docker 容器与初始化智能体

HyperAgents 的所有进化操作都发生在 Docker 容器内的代码副本中，评测完会重置回基线 commit，保证环境干净。

1. 构建镜像（基于 CUDA 13.0，支持 Genesis 物理仿真领域）：

docker build --network=host -t hyperagents .

Dockerfile 还预装了 balrog 领域资产 与 proofgrader 依赖，详见 Dockerfile。

2. 初始化领域智能体。编辑并运行 setup_initial.sh，它默认启用paper_review领域，在 train/val/test 三个子集上评测初始智能体：

bash ./setup_initial.sh

脚本注释中列出了全部可选领域：paper_review、balrog（babyai / babaisai / minihack / nle）、genesis_go2walking、imo_grading、imo_proof、polyglot。切换领域只需取消对应行注释。

四、启动自进化循环：一条命令跑通全量实验

核心入口是 generate_loop.py：

python generate_loop.py --domains paper_review

常用参数速查（完整列表见 generate_loop.py）：

• --max_generation：进化代数，默认 10，新手可先设 2~3 快速验证
• --eval_samples：每领域评测样本数，-1表示全量
• --parent_selection：父代选择策略，如best、score_prop、score_child_prop
• --resume_from：从指定输出目录断点续跑
• --run_baseline：对照实验（no_selfimprove/no_archive/dgm等）
• --optimize_option：只优化智能体 / 只优化集成 / 两者兼有

Balrog 系列领域内置了复古游戏环境，Nethack 的像素图块如下，智能体就是在这样的环境中被反复评测和进化的：

多领域可一次并行，例如：

python generate_loop.py --domains paper_review balrog_nle --max_generation 3

五、解读输出：档案、评分与演化曲线

所有结果保存在outputs/generate_<时间戳>/下，目录结构一目了然：

• archive.jsonl：智能体档案，记录每个节点的分数与血缘关系
• gen_N/agent_output/model_patch.diff：第 N 代 meta agent 产生的代码改动
• gen_N/metadata.json：该代运行元信息
• 各*_eval_*目录：分领域评测预测与报告

每代结束后，generate_loop.py 会自动调用 analysis/plot_progress.py 与 analysis/visualize_archive.py 绘制分数随代数的演化曲线和档案可视化图，无需手动运行分析脚本。多领域还会生成跨领域合并对比图。

六、常见问题与安全提示 ⚠️

• 成本：每代都要调用大模型修改代码 + 全量评测，建议先用小--max_generation和小--eval_samples试跑
• 断点续跑：实验中断后用--resume_from <output_dir>恢复，避免重跑历史代数
• 安全：仓库明确提示，本框架会执行模型生成的不可信代码，建议在隔离的 Docker/云环境中运行，勿在本地敏感机器上直接执行
• 论文复现对照：论文实验日志可通过 README 中提供的链接下载，与outputs/结构对应，方便逐项核对

七、总结：HyperAgents 复现实验清单

1. ✅ 克隆仓库并配置.envAPI Key
2. ✅ 安装 Python 3.12 依赖，docker build构建镜像
3. ✅ 运行setup_initial.sh初始化领域智能体
4. ✅python generate_loop.py --domains <domain>启动自进化循环
5. ✅ 查看outputs/下的档案、diff 与演化曲线，验证智能体逐代变强

至此，你已在本地完整跑通了 HyperAgents 的自指自进化循环——让 AI 修改 AI 的进化范式，正是这篇 arXiv 论文最核心的贡献。

【免费下载链接】HyperAgentsSelf-referential self-improving agents that can optimize for any computable task项目地址: https://gitcode.com/gh_mirrors/hy/HyperAgents