evolving-ai-agents

使用 A-Evolve 进化 AI Agent

概述

A-Evolve 是一种通用基础设施，可使用任意进化算法，在任意领域进化任意 AI Agent，无需手动工程处理。它将所有可进化的 Agent 状态表示为文件（提示词、技能、记忆、工具），针对基准测试运行迭代的求解—观察—进化循环，并利用大模型驱动的变异自动提升 Agent 的性能。

基准测试结果（Claude Opus 4.6）：

• MCP-Atlas：79.4%（第 1 名）
• SWE-bench Verified：76.8%（约第 5 名）
• Terminal-Bench 2.0：76.5%（约第 7 名）
• SkillsBench：34.9%（第 2 名）

何时使用 A-Evolve

在以下情况下使用 A-Evolve：

• 针对可衡量的基准测试优化 Agent 提示词、技能或记忆
• 构建具有自动门控和回滚机制的自我改进型 Agent
• 通过大模型驱动的变异来进化特定领域的工具使用方式和流程
• 运行迭代的求解—观察—进化循环，以最大限度提升 Agent 性能
• 需要为每项更改保留可复现、由 git 版本控制的进化历史

主要区别：其他框架用于_构建_ Agent；A-Evolve 用于_优化_ Agent。它建立在任意 Agent 框架之上，通过自动化进化让 Agent 变得更好。

不要将 A-Evolve 用于：

• 从头构建多 Agent 编排（使用 CrewAI、LangGraph）
• 无需迭代的一次性 Agent 任务（使用 LangChain、LlamaIndex）
• RAG 流水线优化（使用 LlamaIndex、Chroma）
• 不涉及技能／记忆进化的纯提示词优化（使用 DSPy）

快速开始

安装

pip install a-evolve                    # Core
pip install a-evolve[anthropic]         # With Claude support
pip install a-evolve[all]               # All providers

三行代码完成进化

import agent_evolve as ae

evolver = ae.Evolver(agent="swe", benchmark="swe-verified")
results = evolver.run(cycles=10)
print(f"Final score: {results.final_score}")

这会复制内置的 SWE 种子工作区，针对 SWE-bench Verified 运行 10 个进化周期，并返回优化后的 Agent。

核心概念

Agent 工作区

所有可进化状态都以文件形式存放在工作区目录中：

my-agent/
├── manifest.yaml          # Metadata + entrypoint
├── prompts/
│   ├── system.md          # Main system prompt (evolved)
│   └── fragments/         # Modular prompt pieces
├── skills/
│   └── skill-name/
│       └── SKILL.md       # Reusable procedure with frontmatter
├── memory/
│   ├── episodic.jsonl     # Lessons from failures
│   └── semantic.jsonl     # General knowledge
├── tools/
│   ├── registry.yaml      # Tool manifest
│   └── tool_name.py       # Tool implementations
└── evolution/             # Managed by engine (metrics, history)

进化循环

每个周期包含五个阶段：

1. 求解 — Agent 处理基准测试中的一批任务
2. 观察 — 基准测试评估执行轨迹，生成（任务、执行轨迹、反馈）三元组
3. 进化 — 进化引擎根据观察结果变异工作区文件
4. 门控 — 验证变异结果（变异前后创建 git 快照，以便回滚）
5. 重新加载 — Agent 根据进化后的文件系统状态重新初始化

三个可插拔接口

# 1. Agent — implements solve()
class MyAgent(ae.BaseAgent):
    def solve(self, task: ae.Task) -> ae.Trajectory:
        # Domain-specific solving logic
        return ae.Trajectory(task_id=task.id, output=result, steps=steps)

# 2. Benchmark — implements get_tasks() and evaluate()
class MyBenchmark(ae.BenchmarkAdapter):
    def get_tasks(self, split="train", limit=None) -> list[ae.Task]:
        return [ae.Task(id="1", input="...")]

    def evaluate(self, task: ae.Task, trajectory: ae.Trajectory) -> ae.Feedback:
        return ae.Feedback(success=True, score=0.95, detail="Passed")

# 3. Engine — implements step()
class MyEngine(ae.EvolutionEngine):
    def step(self, workspace, observations, history, trial):
        # Mutate workspace based on observations
        return ae.StepResult(mutated=True, summary="Updated prompts")

工作流 1：进化现有 Agent

适用场景：你已有一个可用的 Agent，并希望针对基准测试对其进行优化。

关键要求：

• Agent 实现 BaseAgent.solve() 并返回 Trajectory
• 基准测试实现 BenchmarkAdapter，并提供 get_tasks() 和 evaluate()
• 种子工作区包含 manifest.yaml，其中定义了入口点和可进化层
• 系统提示词位于 prompts/system.md
• 工作区是一个 git 仓库（运行 git init && git add -A && git commit -m "init"）

步骤

import agent_evolve as ae

# Configure evolution parameters
config = ae.EvolveConfig(
    batch_size=10,           # Tasks per solve round
    max_cycles=20,           # Maximum evolution iterations
    evolve_prompts=True,     # Mutate system prompt
    evolve_skills=True,      # Discover and refine skills
    evolve_memory=True,      # Build episodic memory
    evolver_model="us.anthropic.claude-opus-4-6-v1",
)

# Point to your agent workspace and benchmark
evolver = ae.Evolver(
    agent="./my-agent-workspace",
    benchmark="swe-verified",     # Or custom BenchmarkAdapter instance
    config=config,
)

# Run evolution
results = evolver.run(cycles=10)

# Inspect results
print(f"Cycles completed: {results.cycles_completed}")
print(f"Final score: {results.final_score}")
print(f"Converged: {results.converged}")
for cycle_num, score in enumerate(results.score_history):
    print(f"  Cycle {cycle_num + 1}: {score:.3f}")

进化后

工作区现已优化。检查发生了哪些变化：

cd my-agent-workspace
git log --oneline              # See evo-1, evo-2, ... tags
git diff evo-1 evo-10          # Compare first and last evolution
cat prompts/system.md          # Read evolved prompt
ls skills/                     # See discovered skills

工作流 2：添加自定义基准测试

适用场景：你希望在自己的特定领域任务上进化 Agent。

关键要求：

• 定义任务格式（输入、预期输出）
• 实现评分逻辑（0.0–1.0 分）
• 准备任务数据集（拆分为训练集和留出集）

步骤

import agent_evolve as ae

class CodeReviewBenchmark(ae.BenchmarkAdapter):
    """Evaluate agents on code review quality."""

    def get_tasks(self, split="train", limit=None):
        tasks = load_review_dataset(split)
        if limit:
            tasks = tasks[:limit]
        return [
            ae.Task(id=t["id"], input=t["diff"], metadata={"expected": t["comments"]})
            for t in tasks
        ]

    def evaluate(self, task, trajectory):
        expected = task.metadata["expected"]
        actual = trajectory.output
        precision, recall = compute_review_metrics(expected, actual)
        f1 = 2 * precision * recall / (precision + recall + 1e-9)
        return ae.Feedback(
            success=f1 > 0.7,
            score=f1,
            detail=f"P={precision:.2f} R={recall:.2f} F1={f1:.2f}",
        )

# Use with any agent
evolver = ae.Evolver(agent="./my-agent", benchmark=CodeReviewBenchmark())
results = evolver.run(cycles=5)

工作流 3：创建自定义进化引擎

适用场景：默认的大模型驱动变异方式不适合你的领域。

步骤

import agent_evolve as ae

class RuleBasedEngine(ae.EvolutionEngine):
    def step(self, workspace, observations, history, trial):
        failures = [o for o in observations if not o.feedback.success]
        if not failures:
            return ae.StepResult(mutated=False, summary="No failures to address")

        # Analyze failure patterns
        error_types = categorize_errors(failures)
        prompt = workspace.read_prompt()

        # Append learned rules to prompt
        new_rules = generate_rules(error_types)
        workspace.write_prompt(prompt + "\n" + new_rules)

        return ae.StepResult(
            mutated=True,
            summary=f"Added {len(new_rules)} rules from {len(failures)} failures",
        )

evolver = ae.Evolver(
    agent="./my-agent",
    benchmark="my-benchmark",
    engine=RuleBasedEngine(),
)

内置组件

种子 Agent

Agent	领域	模型	主要特性
swe	SWE-bench	Claude Opus 4.6	验证—修复循环、技能提案
terminal	Terminal-Bench	Claude Sonnet 4	并发超时、环境发现
mcp	MCP-Atlas	Claude Opus 4.6	MCP 服务集成

基准测试

名称	领域	指标
swe-verified	代码修补	通过率
mcp-atlas	工具调用	准确率
terminal2	Shell 任务	通过率
skill-bench	多步骤流程	准确率
arc-agi-3	交互式游戏	RHAE 分数

演化算法

算法	策略	最适合
A-Evolve/SkillForge	由大模型驱动的工作区变更	通用场景
Guided Synthesis	以记忆为先，精选技能	技能发现
Adaptive Evolution	奖励跟踪、筛选观察结果	精细控制
Adaptive Skill	以技能为中心的优化	技能密集型领域

配置参考

ae.EvolveConfig(
    batch_size=10,              # Tasks per solve round
    max_cycles=20,              # Max evolution iterations
    holdout_ratio=0.2,          # Test set split for gating
    evolve_prompts=True,        # Mutate system prompts
    evolve_skills=True,         # Discover/refine skills
    evolve_memory=True,         # Build episodic memory
    evolve_tools=False,         # Mutate tool implementations
    trajectory_only=False,      # Hide scores from evolver
    evolver_model="us.anthropic.claude-opus-4-6-v1",
    evolver_max_tokens=16384,
    egl_threshold=0.05,         # Convergence epsilon
    egl_window=3,               # Cycles for plateau detection
)

收敛：如果最近 egl_window 个周期内的分数提升小于 egl_threshold，演化会提前停止。

技能格式

技能是在演化过程中发现并不断优化的可复用流程：

---
name: verify-edge-cases
description: "TRIGGER when: checking boundary conditions. DO NOT TRIGGER: for happy-path tests."
---

## Pattern
Test all falsy-but-valid values: 0, False, "", [], {}

## Process
1. List all input boundaries
2. Run each against the implementation
3. Check both output AND side effects

技能会积累在工作区的 skills/ 目录中。演化器会对其进行整理：接受新技能，合并重叠技能，跳过冗余提案。目标是 5–10 个宽泛技能，而不是 30 个狭窄技能。

常见问题

演化分数过早停滞

原因：批次大小过小，或演化器没有看到足够多样的失败案例。 解决方法：增大 batch_size（尝试 15–20），并确保基准测试任务涵盖多种失败模式。设置 trajectory_only=False，让演化器看到分数。

Agent 工作区变得过大

原因：接受每个提案导致技能库膨胀。 解决方法：默认的 SkillForge 引擎会自动整理技能。如果使用自定义引擎，请实现合并逻辑，以整合重叠技能。

演化期间出现 Git 冲突

原因：多个演化运行使用同一个工作区。 解决方法：每次 evolver.run() 都应使用独立的工作区副本。使用 Evolver(agent="seed-name") 在每次运行时自动复制种子。

演化期间出现大模型提供商错误

原因：演化器模型遇到速率限制或身份验证问题。 解决方法：检查 evolver_model 配置。对于 Bedrock，请确保已配置 AWS 凭证。对于 Anthropic，请设置 ANTHROPIC_API_KEY。

自定义 Agent 未加载演化后的状态

原因：Agent 未实现 reload_from_fs()。 解决方法：在 BaseAgent 子类中重写 reload_from_fs()，以便在每个演化周期后从工作区重新读取提示词、技能和记忆。

Agent 使用说明

加载此技能时：

1. 阅读整个文件，然后再实现任何演化工作流
2. 从快速入门开始——先运行最简化的演化流程，再进行自定义
3. 尽可能使用内置种子——"swe"、"terminal"、"mcp" 提供经过实战检验的配置
4. 在运行演化前，务必在自定义工作区中初始化 git
5. 检查收敛设置——默认的 egl_threshold=0.05 和 egl_window=3 对你的领域而言可能过于严格
6. 每次运行后检查演化状态——阅读 prompts/system.md 和 skills/，了解演化器学到了什么

实用建议：

• 设置 trajectory_only=False（默认值），让演化器看到分数——这能加快学习
• 从 batch_size=10 开始，并根据任务多样性进行调整
• 使用 holdout_ratio=0.2，以防止对训练任务过拟合
• 演化后，git diff evo-1 evo-N 可显示所有变更的累积效果
• 如果演化器未能发现技能，请在 feedback.detail 字符串中补充具体的失败原因

警示信号：

• 分数在各周期之间波动 → 基准测试评估可能不确定
• 技能目录增长到 15 个以上技能 → 引擎未能正确合并或整理技能
• 提示词超过 10K 字符 → 演化只在追加内容，未进行重构
• 2–3 个周期后 converged=True → 增大 egl_window 并减小 egl_threshold

References

• Architecture deep dive: See references/architecture.md
• API reference: See references/api.md
• Step-by-step tutorials: See references/tutorials.md
• Real-world examples: See references/examples.md
• GitHub issues & solutions: See references/issues.md
• Design patterns: See references/design-patterns.md
• Release history: See references/releases.md