hyperagent

Hyperagent

クイックスタート — 簡単な例

Hyperagent を初めて使う方は、セットアップ全体に進む前に、初心者向けの次のタスクを試してみてください。

1. シンプルな Python スクリプトを最適化して高速化する

「hyperagent を使って、このスクリプトを高速化して」と伝え、次のようなコードを貼り付けます：

# slow_sort.py
def sort_numbers(nums):
    result = []
    while nums:
        smallest = min(nums)
        result.append(smallest)
        nums.remove(smallest)
    return result

Hyperagent はベンチマークを実行し、より高速な実装を提案して、改善を検証します。

2. より良い回答が得られるようプロンプトを改善する

「このプロンプトに hyperagent を実行して、精度を改善して」と伝え、次のようなプロンプトを指定します：

Summarize this article in one sentence.

メタエージェントはプロンプトを繰り返し改善し、品質を測定して、より高いスコアを得た改善を採用します。

3. ソート関数をより効率的にする

「この関数を hyperagent で進化させて」と伝え、任意の関数を貼り付けます。Hyperagent はベンチマークを作成し、改善を何世代にもわたって実行して、各世代でのパフォーマンス向上を示します。

4. 任意のスクリプトを自己改善させる

「このエージェント／スクリプトを自己改善して」と伝え、任意の Python ファイルを指定します。Hyperagent はそれを評価ループでラップし、変更を提案して、何が有効かを追跡します。

最もシンプルなセットアップ：METRIC score=0.5 を出力する task.sh を作成してから、python3 scripts/init_session.py を実行します。そこからループが完全に自動化されます。

---

自己言及的な自己改善：あらゆる測定可能な目標を最適化するために、タスクエージェント（およびそれ自体）を変更するメタエージェントです。

Facebook Research の Hyperagents 論文（arXiv:2603.19461）に着想を得ています。同論文では、タスクを解決するエージェントと、自己変更を行うメタレベルを単一の編集可能なプログラムに組み合わせたエージェントが、オープンエンドで累積的な改善を達成し、ドメインを越えてその改善を適用できることが示されました。

仕組み

ハイパーエージェントは、単一の編集可能なコードベースに次の2つのコンポーネントを持つシステムです。

1. タスクエージェント — 対象のタスク（ベンチマーク、コード生成、データ処理など）を解決します
2. メタエージェント — タスクのパフォーマンス履歴を分析し、タスクエージェントのコード（および必要に応じて自身のコード）への変更を提案します

論文の重要な洞察は、メタレベルの変更手順自体が編集可能であれば、システムはタスクのパフォーマンスだけでなく、将来の改善を生み出す仕組みも向上させられるという点です。これにより、累積的で転用可能な成果が実現します。

基本原則

1. 自己言及的な変更

   メタエージェントはタスクエージェントのコードと自身の戦略の両方を変更できます。どちらも同じ編集可能なワークスペースにあります。これにより、改善の仕方を改善するメタ認知的な自己改善が可能になります。

2. 集団ベースの探索（アーカイブ）

   最良のバリアントだけを残すのではなく、成功したすべてのバリアントを次の探索の足掛かりとしてアーカイブに保持します。親の選択では、まだ探索されていない可能性を持つ高性能なバリアントが優先されます。

3. 実証的な評価をすべての判断基準にする

   測定なしに変更が採用されることはありません。候補はすべて、タスクのベンチマークに対して複数回の試行で評価されます。

4. 永続的なメモリとパフォーマンスの追跡

   システムは、すべての実験、仮説、結果の構造化された履歴を保持します。後の世代はそれ以前の知見を基に構築されるため、行き詰まった道を再発見することはありません。

5. ドメインを越えた転用

   メタレベルの改善（パフォーマンスの追跡、評価戦略、仮説生成のパターン）はドメインに依存せず、新しいタスクにも転用できます。

利用可能なスクリプト

• scripts/common.py — 共通ユーティリティ（アーカイブ管理、メトリクス、レポート作成）
• scripts/init_session.py — hyperagent セッションを初期化し、ワークスペースをひな形から作成します
• scripts/run_task.py — タスクエージェントのバリアントを評価し、メトリクスを記録します
• scripts/log_variant.py — 評価済みレコードを記録し、処遇を決定して、アーカイブとレポートを更新します
• scripts/render_report.py — 進化の全履歴を HTML レポートとして生成します
• scripts/select_parent.py — 次の世代のために、アーカイブから親を選択します

Note: generate_variant.py スクリプトはありません。メタエージェントの役割（仮説の生成とコードの変更）は、スクリプトではなく LLM エージェント自体が担います。

すべてのスクリプトは非対話型で、--help を表示し、標準出力に構造化 JSON を出力し、診断情報は標準エラー出力に出力します。

デフォルトのワークフロー

1. 最適化対象を定義した後、セッションを初期化します。

   python3 scripts/init_session.py \
     --goal "Improve prompt accuracy on math benchmark" \
     --metric-name accuracy \
     --unit pct \
     --direction higher \
     --task-command ./task.sh \
     --checks-command ./checks.sh \
     --scope src/agent.py \
     --max-generations 50
   

2. ベースラインを評価します（世代 0）。

   python3 scripts/run_task.py \
     --id gen-000 \
     --hypothesis "Control: unmodified task agent" \
     --change-summary "No modifications" \
     --baseline \
     --output .hyperagent/gen-000.json
   
   python3 scripts/log_variant.py --input .hyperagent/gen-000.json
   

3. 選択 → 変更 → 評価のループを実行します。

   # Select a parent from the archive
   python3 scripts/select_parent.py --output .hyperagent/parent.json
   
   # Generate a variant (meta-agent proposes modifications)
   # This is where YOU (the LLM agent) act as the meta-agent:
   # - Read the parent's code and performance history
   # - Hypothesize an improvement
   # - Apply code modifications
   # - Record what you changed and why
   
   # Evaluate the variant
   python3 scripts/run_task.py \
     --id gen-001 \
     --hypothesis "Add chain-of-thought prompting to improve reasoning" \
     --change-summary "Wrap task prompt in step-by-step reasoning template" \
     --parent gen-000 \
     --output .hyperagent/gen-001.json
   
   python3 scripts/log_variant.py --input .hyperagent/gen-001.json
   

4. いつでもレポートを生成できます。

   python3 scripts/render_report.py
   

事前の Q&A

開始する前に、以下を確認するか、情報を集めてください。

1. 目的 — 何を最適化しますか？
2. 主要メトリクス — 正確な名前、単位、方向（低いほど良い／高いほど良い）
3. タスクコマンド — タスクエージェントを実行し、METRIC name=value 行を出力するスクリプト
4. 正確性ゲート — バリアントを保持するために合格が必要なテストまたはチェック
5. 対象範囲 — メタエージェントが変更できるファイル
6. メタ範囲 — メタエージェントは自身の戦略を変更できますか？（デフォルト：はい）
7. 世代数の上限 — 停止するまでの最大世代数
8. 最小改善しきい値 — デフォルト：1%

ワークスペースのセットアップ

1. 新しいブランチで専用のワークツリーを使用することを推奨します。

   git worktree add ../hyperagent-<goal>-<date> -b hyperagent/<goal>-<date>
   

2. 以下を作成します。

   • hyperagent.md — チェックインする、進化の全履歴を含む永続的なセッション概要
   • task.sh — チェックインする、ベンチマーク実行スクリプト（METRIC name=value を出力）
   • checks.sh — チェックインする、正確性ゲート
   • .hyperagent/ — ローカルの成果物ディレクトリ。チェックインしません

3. 成果物が未追跡のままになるようにします。

   rg -qxF '.hyperagent/' .git/info/exclude || printf '\n.hyperagent/\n' >> .git/info/exclude
   

メタエージェントの役割

あなた（LLM）がメタエージェントです。 各世代での役割は次のとおりです。

1. 親を選択 — scripts/select_parent.py を使用するか、アーカイブに基づいて選択します
2. 分析 — 親のコード、パフォーマンス履歴、過去の実験結果を読みます
3. 仮説を立てる — 効果が期待できる理由を因果関係に基づいて説明した、具体的で検証可能な変更を提案します
4. 変更 — タスクエージェントのコードを変更します（必要に応じて、hyperagent.md にある自身の戦略メモも変更します）
5. 評価 — scripts/run_task.py を実行してバリアントを測定します
6. 記録 — scripts/log_variant.py を使用して結果を記録し、アーカイブを更新します
7. 振り返り — 学んだことを hyperagent.md に反映します

メタレベルの自己変更

メタエージェントは、以下を更新することで自身のプロセスを改善できます。

• hyperagent.md の戦略メモ（仮説生成のパターン、評価のヒューリスティクス）
• .hyperagent/memory.jsonl のメモリエントリ（定性的な知見、修正計画）
• タスク評価プロトコル（副次メトリクスの追加、試行回数の変更）

こうしたメタ改善は世代を重ねるごとに効果が蓄積し、新しいタスクにも引き継がれます。

必須ファイル

hyperagent.md

永続的な契約と進化の履歴です。新しいエージェントは、このファイルから作業を再開できます。

# Hyperagent: <goal>

## Objective
<What is being optimized and why.>

## Configuration
- Primary metric:
- Unit:
- Direction:
- Minimum improvement: X%
- Task command:
- Correctness gates:
- Generation budget:

## Scope
- Task agent files:
- Meta-agent can self-modify: yes/no

## Archive
`.hyperagent/archive.jsonl`

## Lineage
<Tree showing parent→child relationships and which variants were kept>

## Meta-Strategy
<Current approach to hypothesis generation — updated as the meta-agent learns>

## What We've Learned
<Key wins, dead ends, transferable insights>

## Performance Tracking
<Best variant, improvement trajectory, current plateau status>

task.sh

タスクエージェントを実行し、METRIC name=value 行を出力する Bash スクリプトです。

#!/bin/bash
set -euo pipefail
# Run the task agent
python3 src/agent.py --input data/test.json 2>/dev/null
# The agent script should emit: METRIC accuracy=0.85

アーカイブの構造

アーカイブ（.hyperagent/archive.jsonl）には、評価済みのすべてのバリアントが保存されます。

{
  "id": "gen-007",
  "generation": 7,
  "parent_id": "gen-003",
  "timestamp": "2026-03-27T20:00:00Z",
  "hypothesis": "Add few-shot examples to improve pattern recognition",
  "change_summary": "Inserted 3 domain-specific examples into the task prompt",
  "files_touched": ["src/agent.py"],
  "metric_name": "accuracy",
  "direction": "higher",
  "warmup_trials": [0.82, 0.83],
  "measured_trials": [0.85, 0.86, 0.84, 0.85, 0.87],
  "summary": {"median": 0.85, "mean": 0.854, "min": 0.84, "max": 0.87},
  "checks": "passed",
  "disposition": "keep",
  "children_count": 0,
  "meta_modifications": ["Updated strategy notes with few-shot pattern"],
  "reason": "Improved by 3.2% over parent gen-003 (0.824). Checks passed."
}

親の選択

親の選択確率は、以下に比例します。

• パフォーマンススコア（アーカイブの多様性を保つため、高いほど有利）
• 子の数の逆数（まだ十分に調査されていない、高パフォーマンスのバリアントを優先）

これにより、活用（優れたバリアント）と探索（調査が不十分なバリアント）のバランスを取ります。

python3 scripts/select_parent.py
# Output: {"selected_parent": "gen-003", "score": 0.824, "children": 1, "reason": "High performer with few children"}

判断ルール

• keep — 現在のベストをしきい値以上上回り、チェックに合格
• discard — 変種の結果が悪い、同等、または改善幅がしきい値未満
• checks_failed — 指標は改善したものの、正確性のゲートに不合格
• crash — 変種を評価できなかった

プラトーの検出

改善の速度を追跡します。次の場合は停止するか、方針を転換します。

• 改善のない世代が3世代以上連続した
• 仮説の多様性が低下した（アイデアの使い回し）
• 過去5世代の改善速度が世代あたり0.1%未満

ループの動作

次のいずれかに達するまで自律的に実行します。

• 世代の予算を使い切った
• プラトーを検出した（改善のない状態が3世代連続）
• 有望な仮説をすべて検証した
• ユーザーが中断した

ループ中は、次のようにします。

• 1世代につき仮説は1つ
• 行き詰まりを明示的に記録する
• 変種間でワークツリーをクリーンな状態に保つ（破棄した変更を元に戻す）
• 各世代の終了後に hyperagent.md を更新する

よくある落とし穴

1. メタエージェントが自らの戦略に過剰適合する

症状： メタ戦略が初期の成功例に過度に特化する
対処法： 定期的に戦略を見直して範囲を広げ、カテゴリの異なるアプローチを試します

2. アーカイブの肥大化

症状： アーカイブが大きくなり、選択処理が遅くなる
対処法： 50個の変種を処理したら古い世代をアーカイブし、簡潔な要約を維持します

3. 自己変更によるループの不安定化

症状： メタエージェントが評価やログ記録を変更し、ループが壊れる
対処法： 外側のループのスクリプト（init、run、log、select）は変更不可にします。タスクのコードと戦略のメモだけを変更します。

4. 仮説の使い回し

症状： 後の世代で、以前失敗したアイデアを再び試す
対処法： 提案の前に必ず .hyperagent/memory.jsonl を読み、行き詰まりと明示的に照合します。

転送プロトコル

メタ改善を新しいドメインに転送するには、次の手順に従います。

1. hyperagent.md の「What We've Learned」セクションからメタ戦略を抽出する
2. .hyperagent/memory.jsonl を初期知識としてコピーする
3. 転送した戦略を初期コンテキストとして、新しいセッションを開始する
4. メタエージェントはゼロからではなく、蓄積した知見をもとに開始する

レポートの生成

python3 scripts/render_report.py

.hyperagent/report.html を生成し、次の情報を含めます。

• 系譜ツリーの可視化
• 世代ごとのパフォーマンス
• これまでのベストの推移
• 処置の内訳
• 変種ごとの試行分布
• メタ戦略の進化タイムライン