便利なソフトをAIが実際に動かしてわかりやすくレポート

🤖 AI自動レポート column

AIエージェントが自力で賢くなる仕組み「Autocontext」— 繰り返すたびに改善する再帰的ハーネス

タグ AutocontextAIエージェントプロンプト最適化評価ループClaude Code MCPファインチューニング再帰的ハーネスOSScolumnコラムlinuxLinuxwindowsWindowsGitHubオープンソースgreyhaven-aiautocontext
📦 GitHubで見る

AIエージェントが自力で賢くなる仕組み「Autocontext」— 繰り返すたびに改善する再帰的ハーネス

ひとことでいうと

Autocontext（オートコンテキスト）は、AIエージェントが実行を重ねるたびに自動で賢くなるソフトウェアです。自然言語（ふつうの日本語や英語）でゴールを指定するだけで、複数の役割を持つエージェントが評価ループを回し、うまくいったやり方を「プレイブック」として蓄積していきます。同じシナリオへの次回アプローチが自動的に改善されるため、何度も同じ試行錯誤を繰り返す手間が省けます。DSPy や TextGrad などのプロンプト最適化ツールとは異なり、「どう聞くか」だけでなく「何を試み、なぜ変更し、何を学んだか」という構造化された記録と成果物を次世代の実行へ継承するのが最大の特徴です。カスタマーサポートの返答最適化・ローカルモデルの訓練・CI 品質ゲートなど、幅広い用途に使える実用的なツールです。

こんな人におすすめ

1. 特定タスクの AI 品質を底上げしたいプロダクト開発者

カスタマーサポートの返答やコード生成・文書の要約など、「この入力パターンだけ品質が落ちる」という悩みを体系的に解決できます。実験のたびにプレイブックが育つので、チームメンバーが同じ試行錯誤を繰り返さずに済みます。蓄積された知見はチームで共有でき、属人化を防ぐ効果もあります。

2. 本番ログを教師データに活かしたい ML エンジニア・研究者

実際の本番環境のログをそのまま教師データに変換し、コストの安いローカルモデルへ蒸留するワークフローを短期間で構築できます。Anthropic ネイティブのアウトカム分類と JSONL 形式を採用しているため、既存のファインチューニングパイプラインにも接続しやすい設計になっています。Apple Silicon Mac を持つ開発者なら追加インフラなしに試せます。

3. Claude Code や MCP ツールをすでに使っているユーザー

設定ファイルに数行追加するだけで、Claude Code から autocontext_solve_scenario などのツールを自然言語で呼び出せます。「このタスクのスコアを 0.85 以上になるまで改善して」と指示するだけで、エージェントがループを自律実行してくれます。手動でコマンドを叩く手間が大幅に減ります。

インストール・使い方

ターミナル（文字で命令を送る画面）にコマンドを入力して進めます。コピー＆ペーストで使えます。Python 3.12 以上と uv（軽量なパッケージ管理ツール）が必要です。pip でも導入可能です。

Step 1: インストールする

# CLI ツールとしてインストール（推奨）
uv tool install autocontext==0.5.0

# ライブラリとして使いたい場合
uv pip install autocontext==0.5.0

# TypeScript 版を使う場合（JavaScript 環境向け）
bun add -g [email protected]

uv tool install を実行すると autoctx コマンドが使えるようになります。ライブラリ版は自分のプログラムの中に組み込みたいときに選びます。TypeScript 版は JavaScript・Node.js 環境を普段使っている方向けです。

Step 2: プロバイダーを設定してゴールを渡す

# Pi ランタイム（API キー不要・ローカル実行）で試す場合
AUTOCONTEXT_AGENT_PROVIDER=pi \
AUTOCONTEXT_PI_COMMAND=pi \
autoctx solve "improve customer-support replies for billing disputes" \
  --iterations 3

# Anthropic API を使う場合（API キーが必要）
AUTOCONTEXT_AGENT_PROVIDER=anthropic \
ANTHROPIC_API_KEY=sk-ant-... \
autoctx solve "improve customer-support replies for billing disputes" \
  --iterations 3

autoctx solve にゴール文を渡すと、エージェントが自動でシナリオを生成し評価ループを回します。--iterations 3 は「3 世代分ループを回す」という意味です。Pi ランタイムを使えば API キーなしで全体の流れを体験できます。

Step 3: 結果を確認・再生する

# 実行一覧を見る
autoctx list

# 特定の実行の状態を確認する
autoctx status <run_id>

# 第 2 世代の内容を再生する
autoctx replay <run_id> --generation 2

実行が終わると runs/ フォルダ以下に結果が保存されます。autoctx replay を使うと、各世代（＝ループの 1 回ごとの記録）がどんな判断をしたかを後から確認できます。「なぜこの返答になったか」を追跡するのに役立ちます。

Step 4: Claude Code MCP として接続する

.claude/settings.json（Claude Code の設定ファイル）に以下を追加すると、Claude Code から直接 Autocontext のツールを呼び出せるようになります。

{
  "mcpServers": {
    "autocontext": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/autocontext", "autoctx", "mcp-serve"],
      "env": {
        "AUTOCONTEXT_AGENT_PROVIDER": "pi",
        "AUTOCONTEXT_PI_COMMAND": "pi"
      }
    }
  }
}

/path/to/autocontext の部分は、実際に autocontext をクローン（ソースコードをダウンロード）したフォルダのパスに書き換えてください。設定後は Claude Code のチャット欄に自然言語で指示するだけで動きます。

ブラウザで試す（デモ）

インストール前に概念だけ確認したい方は、ブラウザ上でトレース形式やプレイブック生成のコンセプトをインタラクティブに体験できます。実際の LLM（大規模言語モデル）への呼び出しは行わず、autocontext が生成する trace.jsonl の構造と playbook.md の蓄積イメージをビジュアルで確認できます。動作の全体像をつかんでからインストールに進むと、理解がスムーズです。

動かしてみた

Python 3.12.13 の環境でリポジトリ（ソースコードの置き場）の構成を確認しました。Python パッケージ（autocontext/）、TypeScript パッケージ（ts/）、ドキュメント群（docs/）、プロトコル定義（protocol/autocontext-protocol.json）、スクリプト類（scripts/）が整理されて配置されており、全体の見通しがよい構成になっています。

./ts/tsconfig.json
./ts/package.json
./docs/concept-model.md
./docs/scenario-parity-matrix.md
./protocol/autocontext-protocol.json
./packages/package-topology.json

packages/package-topology.json と packages/package-boundaries.json の存在から、Python と TypeScript 双方のモノレポ（複数パッケージを 1 つのリポジトリで管理する構成）として、パッケージの境界が明示的に管理されていることが確認できました。scripts/generate_protocol.py はプロトコル定義を自動生成するスクリプトで、protocol/autocontext-protocol.json との整合性を保つ運用が想定されています。

runs/.gitkeep と knowledge/.gitkeep は、初回クローン時に空フォルダとして存在します。実行後にはここへ各種成果物（トレースやプレイブック）が書き込まれる仕組みになっています。ディレクトリ構成を見るだけでも、データがどこに蓄積されるかがひと目で把握できます。

はじめの一歩：実践のコツ

すぐに動かすためのポイントをまとめます。

  • まず Pi ランタイムで試す: API キーが不要なので、インストール直後に autoctx solve を動かせます。最初は --iterations 2 など少ない反復数からはじめると結果を確認しやすくなります。
  • ゴール文は短く具体的に: 「メール文面をより丁寧にする」「箇条書きの要点を明確にする」など、小さなタスクからはじめると何が起きているか把握しやすいです。
  • autoctx replay で世代を比較する: 各世代の判断を順番に追えるので、改善の流れを学習として読み取ることができます。
  • TypeScript 版は --json フラグが便利: bunx autoctx solve --json とすると構造化出力になり、他のツールとの連携がしやすくなります。
  • Claude Code MCP 接続後は自然言語で指示できる: 「このタスクのスコアを 0.85 以上になるまで改善して」と書くだけで、エージェントがループを自律実行します。コマンドを手動で入力する手間がなくなります。
  • knowledge/ フォルダをチームで共有する: 同じ knowledge/ を使い回すと、一人が学んだプレイブックをチーム全員が活用できます。ナレッジの属人化を防ぎます。

活用例

  • カスタマーサポート返答の品質改善: autoctx solve "improve customer-support replies for billing disputes" --iterations 5 を実行すると、5 世代にわたってエージェントが返答文を試行します。評価スコアの上がった変更だけが knowledge/ に蓄積されるため、次回以降の同類タスクは初回の失敗を繰り返しません。

  • 本番ログから蒸留モデルを作る: instrument_client でラップした Anthropic クライアントが本番トレースを収集し続けます。autoctx build-dataset --outcome success で成功例だけ抽出し、autoctx train で MLX ファインチューニングまで一気通貫で実行できます。Apple Silicon Mac を持つ開発者なら追加インフラなしに試せます。

  • CI でのエージェント品質ゲート: autoctx run <scenario> --iterations 1 を CI（継続的インテグレーション＝自動テストの仕組み）パイプラインに組み込み、出力スコアが閾値を下回った場合にデプロイを止める構成が取れます。trace.jsonl は JSONL 形式なので、既存のログ収集・可視化ツールにもそのまま流せます。

  • プロンプト改善の記録とチーム共有: 実験を重ねるたびにプレイブックが育つので、「なぜこのプロンプトが有効か」という知見がドキュメントとして残ります。チーム全体の品質を均一に底上げできます。

  • 研究・分析用のトレースデータ収集: trace.jsonl にはプロンプト・ツール呼び出し・スコアの時系列が記録されます。エージェントの判断プロセスを構造化データとして分析したい研究者にとっても有用な素材になります。

  • 個人開発での文章・コード改善: ブログ記事の文体改善やコードのリファクタリング提案など、個人プロジェクトの品質向上にも気軽に使えます。小さなゴールを設定して試すだけで、プレイブックが少しずつ育っていきます。

用語とポイント解説

Scenario（シナリオ） 評価可能なタスク定義のことです。かんたんに言うと「AI に解かせる問題のひな形」です。game・agent_task・simulation・artifact_editing・investigation・workflow・negotiation・schema_evolution・tool_fragility・operator_loop・coordination の 11 ファミリーが用意されています。用途に合わせてシナリオを選ぶか、新たに定義することもできます。

Run（ラン） 1 つのシナリオに対する実行セッション全体を指します。かんたんに言うと「1 回の試行セッション」です。1 つの Run は複数の世代（generation）から構成され、各世代が「提案 → 評価 → 分析」のサイクルを担います。実行結果は runs/<run_id>/ 以下に保存されます。

Generation（世代） 1 つの Run の中でループが 1 回転した単位です。かんたんに言うと「改善の 1 ステップ」です。各世代では strategy.json（戦略）・analysis.md（分析）・score.json（スコア）が記録されます。スコアが閾値を下回った変更はロールバック（元の状態への巻き戻し）されます。

Playbook（プレイブック） 有効だと判定された知見を平文 Markdown で蓄積したファイルです。かんたんに言うと「うまくいったやり方のメモ帳」です。次回実行時のコンテキスト（背景情報）として自動的に読み込まれ、同じ失敗を繰り返さない仕組みになっています。

Trace（トレース） trace.jsonl に記録された全イベントの時系列データです。かんたんに言うと「AI が何を考えてどう動いたかの全記録」です。プロンプト・ツール呼び出し・スコアなどが時系列で入っており、autoctx replay で後から再生・確認できます。

Curator（キュレーター） どの知識を knowledge/ へ持ち越すかを審査する役割のエージェントです。かんたんに言うと「学んだことの品質管理係」です。このロールがあることで、質の低い情報が蓄積されるのを防ぎます。プレイブックの信頼性を保つ要となっています。

Competitor（コンペティター） 各世代で新しい戦略やアーティファクト（成果物）を提案する役割のエージェントです。かんたんに言うと「改善案を出す担当者」です。Competitor が提案した内容を他のロールが評価し、採用か却下かを判断します。世代をまたいで異なる戦略が競い合うことで品質が上がります。

Mission（ミッション） VerIFier（検証機）駆動で段階的に進むゴール追跡の単位です。かんたんに言うと「確認しながら進む小目標」です。ゴールが大きい場合に複数の Mission に分割することで、進捗が追いやすくなります。

Campaign（キャンペーン） 複数の Mission を予算・依存関係付きで束ねる TypeScript 側の概念です。かんたんに言うと「Mission をまとめたプロジェクト単位」です。どの Mission を先に実行するか、コストをどう配分するかを設定できます。大規模な改善プロジェクトを管理するときに役立ちます。

instrument_client（インストルメントクライアント） 既存の Anthropic や OpenAI クライアントをラップ（包んで機能を追加）する関数です。かんたんに言うと「本番トレースを自動収集するための薄い包み紙」です。一度ラップするだけで、その後の API 呼び出しがすべて JSONL ファイルに記録されるようになります。既存コードへの変更を最小限に抑えられます。

ぜひカスタマーサポートの返答品質向上や本番ログを活かした蒸留モデルの構築などに活用してみてはいかがでしょうか。