A-EVO-Lab/a-evolve · 上手攻略

仓库：A-EVO-Lab/a-evolve
链接：https://github.com/A-EVO-Lab/a-evolve
分类：agent
作者：Tom
更新：2026-10-23

三证 checklist（写作前自检）

✅ GitHub URL 已 fetch：README、docs/mcp-atlas-demo.md、pyproject.toml、PyPI JSON API 均已实际抓取（fetch 时间 2026-10-23）
✅ 论文/venue 已查证：Position 论文 arXiv 2602.00359（2026）；另有 EMNLP 2026 论文 arXiv 2608.15071（Evo-Harness）、arXiv 2605.30621（EMNLP 2026）
✅ README 子模块 anchor：agent_evolve/algorithms/（4 个参考算法）、agent_evolve/protocol/base_agent.py、agent_evolve/engine/base.py、seed_workspaces/
⚠️ 版本口径：PyPI 最新 a-evolve==0.1.0（唯一发布版本，Development Status :: 4 - Beta），仓库 main 分支最新 commit 18ba996dac98（2026-08-21）。仓库 README 描述的功能面明显大于 0.1.0 轮子所含内容，以源码为准，不要以 PyPI 版为准
⚠️ overhead 数字缺失：README 通篇未给出进化循环的 token 成本、wall-clock 时间、每 cycle 采样量等开销数字，属于待补硬字段，不臆造

这是什么

A-Evolve 是一个 Python 框架，自称「Agentic AI 的 PyTorch」：你给它一个基础 Agent 和一个 benchmark，它自动跑「求解 → 观测 → 进化 → 门控 → 重载」循环，把 Agent 的提示词、技能文件、记忆层直接改写，直到分数不再提升。

它最关键的设计是文件系统契约：所有可进化的状态都落在一个标准目录里，演进引擎靠 LLM 读写这些文件来完成变异，完全不需要知道 Agent 内部实现。

my_agent/
├── manifest.yaml          # 身份、入口、可进化层声明
├── prompts/system.md      # 系统提示词
├── skills/                # SKILL.md 技能库
├── tools/                 # 工具配置
└── memory/                # 情节 + 语义记忆（JSONL）

官方 README 给出的 MCP-Atlas 演化前后对比很直观：种子里 skills/ 是空的、memory/ 是空的，演化后多了 5 个定向技能（entity-verification / search-iteration / multi-requirement / code-execution / conditional-handler）和 6 条 episodic.jsonl 记忆，prompts/system.md 一行没改——也就是说涨点主要来自技能层而非提示词层。每次被接受的变异都打 git tag（evo-1、evo-2…）留作审计。

解决什么问题

手工搭 harness 太贵：每个 benchmark 都要自己写评测循环、变异逻辑、回滚逻辑。A-Evolve 把这部分抽成框架。
提示词调优不可复现：A-Evolve 的门控（Gate）阶段用 holdout 任务验证变异，退步就 git 回滚，每次变异有 tag，等于把 prompt/harness 优化变成可审计的实验记录。
跨领域不通用：多数自改进框架绑定单一环境（Aider、SWE-agent 之类）。A-Evolve 把 Agent、benchmark、进化算法、LLM provider 四个轴全部做成可插拔接口。
自动化 ML 研究本身：README 引用了 arXiv 2606.20657，称其用同一套循环在无人在环下自主后训练 30B Nemotron 四轮，在 NVIDIA Nemotron-Reasoning Challenge 公开榜上以 0.86 对人类最佳 0.87 排到约 4000 份提交中的第 8 位。

README 声称的基准成绩（全部基于单一 Claude Opus-4.6 基座模型，README 标注「Data checked March 2026」）：MCP-Atlas 79.4%（+3.4pp，第 1）、SWE-bench Verified 76.8%（+2.6pp，约第 5）、Terminal-Bench 2.0 76.5%（+13.0pp，约第 7）、SkillsBench 34.9%（+15.2pp，第 2）、ARC-AGI 12.3%（+2.2pp，社区榜第 2）、OSWorld 69.6%（+3.9pp）、SWE-bench Lite 63.7→67.0%、τ-bench 72.7→77.0%、CL-Bench 29.5→34.0%、WebArena-Infinity 72.5→76.3%。⚠️ 这些是作者自报数字，仓库未提供逐任务日志或第三方复现脚本。

快速安装

前置：Python ≥ 3.11（README 徽章写 3.11+，pyproject requires-python = ">=3.11"，classifier 覆盖 3.11/3.12/3.13）。

# PyPI（推荐起步）
pip install a-evolve              # 核心：matplotlib>=3.10、pyyaml>=6.0
pip install "a-evolve[anthropic]"  # + anthropic>=0.30
pip install "a-evolve[mcp]"        # + mcp、strands-agents、datasets、boto3、litellm
pip install "a-evolve[swe]"        # + strands-agents、datasets、boto3、swebench>=3.0.0
pip install "a-evolve[all]"        # anthropic/openai/boto3/datasets/strands-agents/mcp/litellm/swebench/gepa

# 源码开发（README 官方推荐，也是实际能跑通 demo 的路径）
git clone https://github.com/A-EVO-Lab/a-evolve.git && cd a-evolve
pip install -e ".[all,dev]"

验证：

python -c "import agent_evolve; print('OK')"

extras 名称已核对 pyproject：anthropic / openai / bedrock / litellm / swe / mcp / skillbench / osworld / gepa / all / dev。注意 README 表格里写的 bedrock、osworld、skillbench 三个 extra 在正文安装示例里没出现，但 pyproject 里确实存在。

核心用法

1. 三行跑通内置 benchmark

import agent_evolve as ae

evolver = ae.Evolver(
    agent="swe-verified",        # 内置种子工作区，或指向你自己的目录
    benchmark="swe-verified",    # 内置 benchmark 适配器
)
results = evolver.run(cycles=10)

print(f"Final score: {results.final_score:.3f}")
print(f"Converged:   {results.converged}")

内置种子工作区：swe、mcp、terminal、skillbench；内置适配器：swe-verified、mcp-atlas、terminal-bench 2.0、skill-bench，另有 cl-bench 走 examples 目录。

2. 接入自己的 Agent（BYOA）

只需实现一个 solve() 方法：

from agent_evolve.protocol.base_agent import BaseAgent
from agent_evolve.types import Task, Trajectory

class MyAgent(BaseAgent):
    def solve(self, task: Task) -> Trajectory:
        return Trajectory(task_id=task.id, output="result")

evolver = ae.Evolver(agent=MyAgent("./my_workspace"), benchmark="mcp-atlas")
results = evolver.run(cycles=10)

注意 agent= 传字符串（内置名或路径）与传 BaseAgent 实例两种形式并存，写代码时别混。

3. 接入自己的进化算法（BYO-Algo）

from agent_evolve.engine.base import EvolutionEngine
from agent_evolve.types import StepResult

class MyEvolutionEngine(EvolutionEngine):
    def step(self, workspace, observations, history, trial) -> StepResult:
        # 读观测 → 改工作区文件 → 可选跑 trial 任务
        return StepResult(accepted=True, score=new_score)

evolver = ae.Evolver(
    agent="swe-verified",
    benchmark="swe-verified",
    engine=MyEvolutionEngine(config),
)

引擎可选用 TrialRunner（按需验证）、EvolutionHistory（观测与版本查询）、VersionControl（git 回滚）三组共享原语，但都是可选的。四个内置参考算法与各自最佳成绩：adaptive_evolve（MCP-Atlas 79.4%）、adaptive_skill（Terminal-Bench 2.0 76.5%）、skillforge（SkillsBench 34.9%）、guided_synth（SWE-bench 76.8%）。

4. MCP-Atlas 实跑（以 docs/mcp-atlas-demo.md 为准）

uv venv .venv --python 3.11
uv pip install -e ".[mcp,dev]"
docker pull ghcr.io/scaleapi/mcp-atlas:latest

export AWS_DEFAULT_REGION=us-west-2     # 或用 ANTHROPIC_API_KEY + --provider anthropic
export MCP_ENV_FILE=.env                # 36 个 MCP server 中有 16 个要第三方 API key

uv run python examples/mcp_examples/adaptive_evolve_all.py \
  --env-file .env \
  --docker-image ghcr.io/scaleapi/mcp-atlas:latest

默认 solver 是 strands-agents + Bedrock Claude Sonnet（us.anthropic.claude-sonnet-4-20250514）。key 缺失的任务会被自动过滤掉——这意味着你能跑的任务集合取决于你配了几个 key，复现别人的分数前先对齐 key 覆盖面。

典型适用场景

研究新的自我进化算法：这是它最被认可的场景。四个轴全可插接，新算法丢进 agent_evolve/algorithms/your_algo/ 就能白嫖多套 benchmark、标准化工作区、门控与日志。
Benchmark 作者接入新评测域：实现 BenchmarkAdapter 的 get_tasks() 与 evaluate() 两个方法即可。
把某个成熟 Agent 的 harness 经验迁到另一个 Agent：README 记录了把在 Terminal-Bench 2.0 上学到的 harness 与技能直接移植到 ClawCode，TB2 从 67.8% → 72.9%（+5.1pp）。
企业内部 agent 迭代：目录即契约的设计对「提示词 + 技能 + 记忆」这类可文件化状态很友好。

坑与注意

README 里的 demo 文档链接大面积 404。README Quick Start 处链接 docs/swe-bench-demo.md、docs/terminal-bench-demo.md，但 main 分支 docs/ 目录实际只有 algorithms/、mcp-atlas-demo.md、skillbench-setup.md。已实测 https://raw.githubusercontent.com/A-EVO-Lab/a-evolve/main/docs/swe-bench-demo.md 返回 404。现象：照 README 点链接空欢喜；影响：swe / terminal 两条最热的路径没有可读文档，只能读源码；修复：直接读 seed_workspaces/、agent_evolve/benchmarks/ 源码，或切到 main-dev、release/* 等分支找文档。
PyPI 版本严重落后于仓库。a-evolve==0.1.0 是唯一发布版，而 README 描述了 4 个算法、10 个 benchmark 成绩、OSWorld/GEPA/Meta-Harness 等一整套东西。现象：pip install a-evolve 后 import agent_evolve 能过，但 Evolver(agent=..., benchmark=...) 报缺模块/属性；影响：按 README 写代码却跑不起来，误以为是自己写错；修复：一律用 pip install -e ".[all,dev]" 走源码，或先 pip download a-evolve==0.1.0 解包核对到底有什么。
分支命名暗示这是活跃实验场，main 之外还有 feat/cl-bench、feat/osworld-benchmark、feat/propose-curate-engine、feat/training-evolve-v1、release/evo-harness、release/adaptive-auto-harness 等分支。现象：不同分支 API 可能不一致；影响：照某分支博客/issue 抄代码装不上；修复：锁 commit 用（当前 main 为 18ba996dac98），别锁分支名。
benchmark 门槛比想象中高。MCP-Atlas 要 Docker + 16 家第三方 API key；SWE-bench 要 swebench>=3.0.0 与数据集下载。现象：KeyRegistry 缺 key 时任务被静默过滤，分数虚高或样本不同；影响：跑出来的数字没法跟 leaderboard 对齐；修复：记录本次实际覆盖的任务数与缺失 key 列表，报告里写清。
MCP-Atlas 的 Docker 通信是 docker exec -i 走 stdio，不是容器网络。现象：容器内 localhost 指向容器自己；影响：连外部服务失败；修复：按 demo 文档把 key 通过 server_keys.yaml / MCP_ENV_FILE 注入容器，而不是在 SQL/脚本里写地址。
API key 数量多、易泄露。demo 文档列出的 .env 模板含 BRAVE_API_KEY、SLACK_MCP_XOXC_TOKEN、GOOGLE_REFRESH_TOKEN、MONGODB_CONNECTION_STRING 等 18 个变量，其中若干带真实凭据前缀。现象：把 .env 提交进仓库或贴进 issue；影响：凭据外泄；修复：.env 已在 .gitignore（文档如此声明），只用环境变量注入，截图前抹掉。
门控依赖 holdout 划分，划分方式直接决定能不能收敛。README 说收敛条件是「EGL（Evolutionary Generality Loss）稳定或达到 max_cycles」。现象：cycle 跑满仍不收敛、分数来回抖；影响：算力白烧；修复：先用小 cycles 观察 results.converged 与 tag 序列，再决定是否加预算。
进化即写文件，Agent 需要能 reload。契约要求 Agent 在演化后重新加载工作区。现象：你的 Agent 只在启动时读一次提示词/技能，演化完分数纹丝不动；影响：看起来是算法无效，其实是接线问题；修复：对照 manifest.yaml 里声明的 evolvable layers 确认 reload 路径。
成本数字全缺。README 与文档均未给出每 cycle 的 token 消耗、采样量、耗时。现象：只能靠自己的账单估；影响：无法做 ROI 决策；修复：先在最小 benchmark（skill-bench 或 cl-bench）跑 3~5 cycle 自测成本曲线。
成绩自报且数据时点为 2026-03。README 明确写「Data checked March 2026」，与当前 2026-10 已隔约 7 个月，期间的模型与榜单均已变动。现象：拿旧分数对今天的新榜；影响：结论失真；修复：引用时必须带上「2026-03 数据口径」这句限定。

与同类对比

vs. DSPy / GEPA / MIPROv2：这类是提示词/程序级优化器，优化对象窄但成本低。A-Evolve 是更外层的基础设施，能把技能文件、记忆 JSONL 一起纳入变异；DSPy 类通常没有 benchmark 门控回滚机制。
vs. Agent scaffold（SWE-agent、Aider）：它们是「一个」Agent，A-Evolve 是「进化 Agent 的引擎」，理论上可把前者当 BaseAgent 塞进去（官方内置 SweAgent、McpAgent 即此思路）。
vs. OpenEvolve / AlphaEvolve 系：AlphaEvolve 未开源；OpenEvolve 更偏代码演化。A-Evolve 的差异点是文件系统契约 + git tag 审计 + 多 benchmark 适配器。
vs. AutoResearchClaw / Orch-Research：README 提到已被这两个项目集成，属于「被采用」关系而非竞品。

一句话推荐结论

推荐，但要按研究基础设施而不是「拿来提效的工具」来用它——它的真正价值在于给自我进化研究提供可复现的门控 + git 审计 + 多领域适配层；但 0.1.0 的 PyPI 版本与 README 描述严重脱节、若干核心文档 404、无任何成本与第三方复现数据，所以动手前先 pip install -e ".[all,dev]" 并自己标定一次成本，别被 leaderboard 数字直接说服。