AutoSaddler、LLM エージェントのハルネス最適化を自動実行

🛠️ AutoSaddler：エージェント実行トレースから得られる耐久性のある更新による自動ハーネス最適化

AutoSaddler は、実行トレースの診断を通じて、プロンプト・ツール・ミドルウェアへの構造化された更新を適用し、一般化する変更を選択することで、LLM エージェント用ハーネスを自動的に改善します。

📄 論文 · 🌐 プロジェクトサイト · 🎥 短編動画

予備的な結果として、各ベンチマークおよびエージェントハーネスにおけるテストの Pass@1 スコアは以下の通りです：

各モデルの結果、アブレーション実験、計算効率の比較グラフ、最適化の推移については、論文 または インタラクティブなプロジェクトページ をご覧ください。

✨ 主な特徴

• フルハーネス最適化: プロンプト、ツールの定義と実装、ミドルウェアフック、エージェントループのロジック全体を検索範囲に含めます。

• 詳細な診断: 表面的な自己分析に頼るのではなく、実行トレースやハーネスコードベースを深くデバッグし、根本原因を特定します。

• 構造化された介入: プロンプト、ツール、ミドルウェアに対して、無制限な編集を行う代わりに、明確なパッチ分類体系と段階的な「Capability-to-Steering」スケジュールに基づいて対応します。

• 一般化を意識した選定: 動機付けられた実行経路以外のケースでも更新を検証し、進化 DAG（EvoDAG）を用いた自己分析を通じて、広く役立つ教訓を保持します。

• 堅牢な実行: 追加のみが可能なイベント記録、変更不可能な出所証明、再開可能な状態管理、コンテンツアドレス指定された候補を備えています。

📣 ニュース

• 2026-08-25: GAIA2 上の Meta-ARE ハーネスの最適化に対応する V2 を追加しました。

• 2026-08-24: AutoSaddler の論文を arXiv v1 として公開し、プロジェクトページとショート動画 も同時にリリースしました。

🛠️ インストール

AutoSaddler を使用するには、Python 3.12〜3.14、uv、Git が必要です。

git clone https://github.com/microsoft/AutoSaddler.git
cd AutoSaddler
uv sync --extra dev

このリポジトリの Python コマンドは、uv run を通じて実行できます。

🚀 クイックスタート

認証情報を必要としない決定論的な V2 テンプレートを実行し、最適化エンジン、イベントストア、候補進化、出力投影を動作させてみましょう：

uv run python -m autosaddler.v2.cli \
  --config configs/v2/local_template.yaml \
  --run-id local-template

このコマンドを繰り返すと、解決された入力が検証された後、同じ実行が再開されます。

🧭 バージョン

• V2（最新）： この README で文書化されている、永続的でプラグインベースの実装です。新規ユーザーや統合プロジェクトはここから始めることをお勧めします。

• V1（レガシー）： arXiv の論文で実験に使用された研究品質の実装です。論文の再現と参照のために残されています。詳細は V1 README をご覧ください。

🗂️ リポジトリ構造

AutoSaddler/
├── configs/                 # V1/V2 configs and benchmark split manifests
├── docs/                    # Architecture and scenario-integration guides
├── figures/                 # README and paper figures
├── scripts/                 # Data provisioning and legacy launch scripts
├── src/autosaddler/v1/      # Legacy implementation
├── src/autosaddler/v2/      # Current engine, plugins, providers, and storage
└── tests/                   # Characterization and focused V2 tests

現在の実装については、V2 アーキテクチャガイド から始めてください。

🧩 仕組み

AutoSaddler は、ハネス最適化をオフラインのミニバッチ学習として定式化します。最適化ライフサイクル全体で 3 つのセッションタイプを使用します：

• 診断・パッチ： 失敗したトレースとハネスコードベースを検査し、構造化された Capability パッチ（コードまたはインフラストラクチャ）と Steering パッチ（テキストによる動作変更）を提案します。

• リフレクション： パッチ適用前後のトレースを比較し、修正済み、回帰、未解決、継続して成功したケースを分類し、再利用可能な教訓を記録します。

進化 (Evolution): 完全な EvoDAG を参照し、成功したコンポーネントや各系統からの教訓を統合して候補を生成します。

候補の更新はサンプリングされたトレーニングケースで検証され、開発用スプリットによってゲート処理されます。ロールアウト予算が尽きた時点で、AutoSaddler は開発用データセット上で最高ランクの候補を返します。イベントライフサイクルと不変条件については、V2 アーキテクチャガイド をご覧ください。

🎯 対応するハーネスとベンチマーク

現在のリポジトリには以下のものが含まれています：

V2 では、不変でコンテンツアドレス指定されたコンポーネントマップと Git キャンディデートスペースをサポートしています。オプティマイザーセッションでは、組み込みのフェイクプロバイダー、Anthropic Claude Agent SDK、または GitHub Copilot SDK 転送を利用できます。

OpenClaw や Codex などの追加ハーネスや、Terminal-Bench などのベンチマーク向けの統合機能も近日公開予定です。お楽しみに！

⚙️ 設定

V2 の設定はすべて schema_version: autosaddler/v2 で始まります。

シナリオプラグインは、AutoSaddler の汎用最適化エンジンと特定のハーネス/ベンチマークペアをつなぐアダプターです。これにより、ハーネス空間、ケース、評価機能、証拠、プロンプト、機能、再現性メタデータが提供されます。設定ではこのプラグインを選択し、4 つの明確な所有領域を宣言します。

設定ファイルの例：

設定は厳格で、失敗時にクローズ（停止）する仕様です。解決された入力がバイト単位で完全に同一である場合のみ、実行 ID を再利用できます。ソースの改訂、マニフェスト、設定、または出所情報に変更があれば、実行は拒否されます。

🔬 同梱の GAIA2 スモークテストの実行再現

チェックインされた V2 のスモーク設定では、7 つの GAIA2 シナリオに対して実際の最適化パイプラインが実行されます。これは 6 つのトレーニングケースと 1 つの開発ケースで構成され、2 回の最適化イテレーションを行います。これは論文全体の試験ではなく、範囲を限定した統合テストであり、数時間かかる可能性があり、プロバイダへの課金が発生します。

1. リポジトリの準備

以下の兄弟ディレクトリ構成を使用してください：

<parent>/
|-- AutoSaddler/
|-- Meta-ARE/
|-- meta_are_data/
`-- working_dir/

設定ファイルで固定されたリビジョンにある、適応版 Meta-ARE リポジトリをクローンします：

cd ..
git clone https://github.com/pshlego/Meta-ARE.git Meta-ARE
git -C Meta-ARE checkout --detach 2419824a94fb8211fc8227ada7bff1b29f86e563
mkdir -p working_dir
cd AutoSaddler
uv sync --extra meta-are-setup

2. ベンチマーク入力の用意

ピン留めされた Hugging Face リビジョンから、マニフェストで選択された 7 つの GAIA2 ペイロードをプロビジョニングします。

HF_TOKEN はこの公開データセットでは必須ではありませんが、匿名利用時のレート制限を回避するために設定できます：

uv run --extra meta-are-setup python scripts/meta_are/provision_gaia2_scenarios.py \
  --destination-root "$PWD/../Meta-ARE/datasets_local/gaia2" \
  --revision 78ea3bdbdeec2bdcd6afa5420915d8a22f23ed99

コマンドを実行すると、"file_count": 7 が出力されるはずです。次に、約 260 MB のデモファイルシステムをプロビジョニングします。

uv run --extra meta-are-setup python scripts/meta_are/provision_demo_filesystem.py \
  --destination-root "$PWD/../meta_are_data/gaia2_filesystem" \
  --revision 132e26376f5e963bb59f64bcccdd02188cb08dee \
  --meta-are-project ../Meta-ARE

両方のコマンドは冪等性を持ち、ソースの改訂履歴とコンテンツのダイジェストを記録します。また、ローカルファイルの不整合を検出すると実行を拒否します。評価プロセスでは、Hugging Face のクライアントがオフラインモードに強制されます。

3. プロバイダーの設定と実行

スモークテストの設定では、タスクエージェントとジャッジには OpenAI の gpt-4.1-mini を、最適化処理には Anthropic の claude-opus-4-6 を使用します：

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."

外部の作業ディレクトリから実行して、生成されたワークスペースが Git の履歴を通じてリポジトリレベルのエージェント指示を継承しないようにしてください。独立した各実行には新しいラン ID を使用します:

cd ../working_dir
RUN_ID="meta-are-smoke-$(date -u +%Y%m%dT%H%M%SZ)"
printf 'run_id=%s\n' "$RUN_ID"
uv run --project ../AutoSaddler \
  python -m autosaddler.v2.cli \
  --config ../AutoSaddler/configs/v2/meta_are_smoke.yaml \
  --run-id "$RUN_ID"

実行結果は working_dir/outputs/v2_meta_are/runs/<run-id>/ ディレクトリに格納されます。成功すると、"iterations": 2 が含まれる result.json が作成され、選択された候補と開発スコアが出力されます。

ランアーティファクトと再開について

ランは自己完結型であり、以下の要素を含めることができます:

<run-root>/<run-id>/
├── events.jsonl
├── manifest.json
├── snapshot.json
├── evolution_dag.json
├── metrics.jsonl
├── metrics-summary.json
├── result.json
├── resolved/
├── candidates/
├── evaluations/
├── sessions/
├── mutation-deltas/  # Git harnesses only
└── workspaces/

events.jsonl が正式な記録源です。中断後に再開する場合は、その実行 ID を使用しているプロセスがないことを確認し、同じ入力条件で同じコマンドを再度実行してください。1 つの実行 ID に複数のプロセスが同時にアクセスすることは絶対に避けてください。

実行結果を共有する前に、必ず sessions/ ディレクトリと evaluations/ ディレクトリを確認してください。トレーシングデータにはプロンプトが含まれている可能性があるためです。

レスポンス、ツールの引数、作業ディレクトリ、リポジトリのメタデータ、またはその他の機密データを扱う際にも注意が必要です。

検証済みの非終端チェックポイントを新しい実行にブランチするには:

uv run python -m autosaddler.v2.cli \
  --config CONFIG.yaml \
  --run-id NEW_RUN_ID \
  --fork-from-run-id SOURCE_RUN_ID \
  --fork-through-sequence LAST_EVENT_SEQUENCE

フォークを初期化する際に差異が許されるのは optimization.budget.max_iterations だけです。レガシーなチェックポイントのインポートはできません。

🔌 ハーネスまたはベンチマークの追加

V2 シナリオプラグインは、ハネス空間、評価器、証拠ビルダー、プロンプトパック、学習用と開発用のケースの分離、プロバイダ機能、解決された出所情報など、統合境界を管理します。

組み込みの統合機能は src/autosaddler/v2/plugins/ ディレクトリ下に配置されています。外部パッケージは、このリポジトリにシナリオ固有のコードを追加することなく、autosaddler.scenarios エントリーポイントグループを通じてプラグインを登録できます。AutoSaddler は、重複する名前や API バージョンの不整合、記述子の不備、およびプラグインの読み込み失敗を検出すると拒否します。

所有権チェックリスト、パッケージ構成、登録契約、テスト、およびスモーク設定の要件については、シナリオ統合ガイド を参照してください。最小限の決定論的な例として src/autosaddler/v2/plugins/fake.py を、本番環境向けの Git ハーネス例として src/autosaddler/v2/plugins/meta_are/ を活用するのがおすすめです。

統合ガイドに従ってコーディングエージェントにシナリオ統合を実施することも推奨されます。

🧰 開発とプロジェクトの方針

uv sync --extra dev
uv run ruff check src/autosaddler tests/
uv run python -m pytest tests/ -v --tb=short
uv build

本プロジェクトへの貢献は歓迎されます。詳細は CONTRIBUTING.md をご覧ください。

本プロジェクトは、Microsoft オープンソース行動規範 に従い、セキュリティ報告ポリシー を公開しています。また、ライセンスは MIT License です。

📝 引用

@misc{park2026autosaddlerautomaticharnessoptimization,
  title={AutoSaddler: Automatic Harness Optimization with Durable Updates from Agent Execution Traces},
  author={Sungho Park and Wonjoong Kim and Rongyuan Tan and Jue Zhang and Wook-Shin Han and Pengfei Gao and Chanyoung Park and Yongqiang Yao and Rao Fu and Elsie Nallipogu and Qingwei Lin and Saravan Rajmohan and Dongmei Zhang},
  year={2026},
  eprint={2608.23041},
  archivePrefix={arXiv},
  primaryClass={cs.AI},
  url={https://arxiv.org/abs/2608.23041},
}