evolving-ai-agents

A-EvolveによるAIエージェントの進化

概要

A-Evolveは、手動でのエンジニアリングを一切行わずに、あらゆるドメインのあらゆるAIエージェントを、あらゆる進化アルゴリズムで進化させるための汎用インフラストラクチャです。進化可能なエージェントの状態をすべてファイル（プロンプト、スキル、メモリ、ツール）として表し、ベンチマークに対して反復的な「解決・観察・進化」サイクルを実行し、LLM 主導の変異を使ってエージェントの性能を自動的に向上させます。

ベンチマーク結果（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を使用する場面：

• 測定可能なベンチマークに対してエージェントのプロンプト、スキル、メモリを最適化する
• 自動ゲーティングとロールバックを備えた自己改善型エージェントを構築する
• LLM 主導の変異を通じて、ドメイン固有のツール使用法や手順を進化させる
• エージェントの性能を最大化するために、反復的な「解決・観察・進化」ループを実行する
• あらゆる変更について、再現可能で Git にバージョン管理された進化の履歴が必要である

主な差別化要因：他のフレームワークはエージェントを 構築 しますが、A-Evolveはエージェントを 最適化 します。あらゆるエージェントフレームワーク上に構築され、自動進化によってエージェントを改善します。

A-Evolveを使用しない場面：

• マルチエージェントのオーケストレーションをゼロから構築する場合（CrewAI、LangGraphを使用）
• 反復が不要な単発のエージェントタスクの場合（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

3行で進化を実行

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回の進化サイクルを実行して、最適化されたエージェントを返します。

基本概念

エージェントワークスペース

進化可能な状態はすべて、ワークスペースディレクトリ内のファイルとして格納されます。

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)

進化ループ

各サイクルは次の5つのフェーズで構成されます。

1. 解決 — エージェントがベンチマークのタスクバッチを処理します
2. 観察 — ベンチマークが実行履歴を評価し、（タスク、実行履歴、フィードバック）の組を生成します
3. 進化 — 進化エンジンが観察結果に基づいてワークスペースのファイルを変異させます
4. ゲート — 変異を検証します（ロールバックのため、変更前後の Git スナップショットを取得します）
5. 再読み込み — エージェントが進化後のファイルシステムの状態から再初期化されます

3つのプラグイン可能なインターフェース

# 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：既存のエージェントを進化させる

使用する場面：動作するエージェントがあり、ベンチマークに対して最適化したい場合。

必須要件：

• エージェントが Trajectory を返す BaseAgent.solve() を実装している
• ベンチマークが get_tasks() と evaluate() を備えた BenchmarkAdapter を実装している
• シードワークスペースに、エントリーポイントと進化可能なレイヤーを記述した 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：カスタムベンチマークを追加する

使用する場面：独自のドメイン固有タスクでエージェントを進化させたい場合。

必須要件：

• タスク形式（入力、期待される出力）を定義する
• スコアリングロジック（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：カスタム進化エンジンを作成する

使用する場面：デフォルトの LLM 主導の変異がドメインに適さない場合。

手順

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(),
)

組み込みコンポーネント

シードエージェント

エージェント	ドメイン	モデル	主な機能
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	シェルタスク	合格率
skill-bench	複数ステップの手順	精度
arc-agi-3	インタラクティブゲーム	RHAE スコア

進化アルゴリズム

アルゴリズム	戦略	最適な用途
A-Evolve/SkillForge	LLM によるワークスペースの変更	汎用
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/ ディレクトリに蓄積されます。進化器がスキルを整理し、新しいスキルは採用し（ACCEPT）、重複するスキルは統合し（MERGE）、冗長な提案はスキップします（SKIP）。目標は、細分化されたスキルを30個用意するのではなく、幅広く使えるスキルを5～10個用意することです。

よくある問題

進化スコアが早期に頭打ちになる

原因：バッチサイズが小さすぎるか、進化器が十分な失敗の多様性を確認できていません。 対処法：batch_size を増やし（15～20を試してください）、ベンチマークタスクが多様な失敗パターンをカバーするようにします。進化器がスコアを確認できるよう、trajectory_only=False を設定します。

エージェントのワークスペースが大きくなりすぎる

原因：すべての提案を採用したことでスキルライブラリが肥大化しています。 対処法：デフォルトの SkillForge エンジンはスキルを自動的に整理します。カスタムエンジンを使用する場合は、重複するスキルを統合するマージロジックを実装してください。

進化中に Git の競合が発生する

原因：同じワークスペースで複数の進化を実行しています。 対処法：各 evolver.run() は独自のワークスペースコピーで動作させてください。Evolver(agent="seed-name") を使用すると、毎回シードが自動的にコピーされます。

進化中に LLM プロバイダーのエラーが発生する

原因：進化器モデルのレート制限または認証の問題です。 対処法：evolver_model の設定を確認してください。Bedrock の場合は、AWS 認証情報が設定されていることを確認します。Anthropic の場合は、ANTHROPIC_API_KEY を設定します。

カスタムエージェントが進化後の状態を反映しない

原因：エージェントに reload_from_fs() が実装されていません。 対処法：BaseAgent のサブクラスで reload_from_fs() をオーバーライドし、各進化サイクル後にワークスペースからプロンプト、スキル、メモリを再読み込みするようにします。

エージェント向け使用手順

このスキルが読み込まれたら：

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