メインコンテンツへ移動
AIチュートリアル

AstraとJEVのMinecraftエージェントを実行・検証する

Minecraft Java 1.16.5向けAstraとJEVエージェントのインストール、設定、起動、テスト、記録、検証方法を解説します。プランナーとアクションのアーキテクチャ、認証情報の管理、新規ワールドの設定、ネイティブクライアントのワークフロー、証拠ファイル、高度な戦闘および録画に関する考慮事項を説明します。

約22分で読了
AstraとJEVのMinecraftエージェントを実行・検証する

プロジェクトの概要

AstraおよびJEVのMinecraftエージェントは、構造化されたゲーム観測と制限付きのプレイヤー操作を使用して、あらかじめ定義されたMinecraft Java 1.16.5のルートを完了します。GPT-6 Astra、または任意でGPT-5.6 Solが、目標、対象アイテム、移動ウェイポイントを計画します。続いてJEVが利用可能なアクションを選択し、Mineflayerが移動、経路探索、通常のゲームプロトコル通信を実行します。

これはスクリーンショットだけによる操作ではなく、個々のキーボード入力をエミュレートするものでもありません。モデルは、読み込まれたチャンク内のブロックや、既知のシードに対して提供された座標など、構造化された状態を受け取ります。利用可能なアクションには、移動、1ブロックの採掘、ドロップアイテムの回収、クラフト、チェストを開く、食事、睡眠、戦闘操作が含まれます。

最新の検証済み実行 nether-final-08 は、8分43.300秒で完了しました。新しいサバイバルワールドのピースフル難易度で、空のインベントリから開始し、ネザーを通過して移動した後、初回の着地で6回のベッド爆発によりエンダードラゴンを倒し、体力満タンかつ死亡なしで脱出ポータルに入りました。この実行では、JEVの判断を131回、Astraの呼び出しを35回行いました。

このプロジェクトは公式バニラサーバーを使用し、選択したアクションを通常のプレイヤープロトコルで送信します。Java製のドラゴンセンサーは読み取り専用で、ドラゴンの頭部の正確な位置を報告しますが、アイテムの付与、エンティティの移動、体力の変更、ゲームルールの変更は行いません。

主な機能

  • モデル役割の分離: AstraまたはSolが現在の目標を計画し、JEVが現在の観測から制限された1つのアクションを選択します。
  • 通常のMinecraft操作: Mineflayerが移動、経路探索、ブロック操作、クラフト、インベントリ操作、プロトコル通信を処理します。
  • ネザーを利用したルート: 固定ルートでは、エンドでの戦闘前にネザーを移動の近道として使用します。
  • 読み取り専用のドラゴン観測: ローカルのJavaセンサーがドラゴンの頭部の位置を報告し、エンティティの状態を変更せずにベッドのタイミングを正確に計れるようにします。
  • ネイティブ録画: 非表示の公式Minecraft Java 1.16.5クライアントが、ネイティブモデル、テクスチャ、アニメーション、インベントリ画面、体力、満腹度、空気量、ホットバーの状態、手に持ったアイテム、ドラゴンの体力を描画します。
  • 制御されたカメラ移動: カメラの旋回は、各軸で毎秒240度、加速度は毎秒960度に制限されています。
  • 構造化された証拠: JSONLイベントログ、ステータスファイル、勝利の証拠、動画マニフェスト、ワールド状態のチェックにより、後から検証できます。
  • 自動テスト: リポジトリには、完了イベント、ネイティブパケット、アクションポリシー、経路探索のキャンセルを検査するチェックが含まれています。

アーキテクチャとモデル設定

デフォルトのプランナーモデルは openai/gpt-6-astra で、/api/v1/chat/completions を通じて呼び出されます。PLANNER_MODEL 環境変数で openai/gpt-5.6-sol を選択できます。JEVは /api/alpha/decisions を通じて typesafe/jev-1.13 を使用します。

プランナーが任意の手順列を直接実行することはありません。プランナーは現在の目標、必要なアイテム、ウェイポイントを設定します。JEVは現在の構造化された観測を評価し、許可されたアクションを1つ選択します。この分離により、個々の判断を制限しながら、実行全体ではより長い計画に沿って進められます。

要件と重要な制限事項

起動スクリプトとネイティブレンダリングスクリプトはmacOS上で開発されました。別のオペレーティングシステムでは、ランタイムパス、Javaの場所、ローカルサーバー設定を適宜変更する必要があります。付属のネイティブ起動スクリプトは、独自のローカルJava 17ランタイムを使用します。

Node.jsとnpm、ネイティブクライアントスクリプト用のPython 3、互換性のあるJavaランタイム、Google Application Default Credentials、OpenRouterキーを含むGoogle Secret Managerシークレットへのアクセス、十分なOpenRouterクレジットが必要です。Minecraftのバイナリ、ダウンロードしたランタイム、保存ワールド、録画、認証情報は意図的にGitから除外されています。

文書化されているゲーム設定は次のとおりです。

  • シード: 8398967436125155523
  • モード: Survival
  • 検証済み録画で使用した難易度: Peaceful
  • 有効なエンドポータルの中心: -1130, 34, 856
  • メインサーバー: 127.0.0.1:25576
  • ステータスエンドポイント: http://127.0.0.1:3078
  • エージェントが使用するローカルドラゴンセンサーのエンドポイント: http://127.0.0.1:3093
  • ネイティブプロトコルミラーのポート: 25578

このシードには、村、黒曜石21個が入った3つの補給チェスト、自然に有効化されたエンドポータルがあります。文書化されたルートでは、ブレイズロッドは必要ありません。座標は別のテストワールドで調査されていますが、最終実行時の移動と設置は通常のプレイヤー操作を使用します。

ステップ1: Node.jsの依存関係をインストールする

リポジトリのルートから、プロジェクトのパッケージをインストールします。

npm install

これにより、エージェント、モデルリレー、ルートロジック、証拠ツール、テストで使用するJavaScript依存関係がインストールされます。

ステップ2: 安全なモデルアクセスを設定する

エージェントは一般的な OPENROUTER_API_KEY 環境変数を意図的に無視します。代わりに、モデル呼び出し時にGoogle Secret Managerからキーを読み込み、プロセスメモリ内だけに保持します。キーをソースファイルや実行ログに記録してはいけません。

  1. model-relay.mjsとmodels.mjsを開きます。
  2. 元のデプロイで使用されているGoogle Cloudプロジェクトとシークレットへの参照を、自分のプロジェクト用の参照に置き換えます。
  3. Google Application Default Credentialsを使用してローカルで認証します。
  4. 認証済みのIDに、選択したシークレットへのアクセス権限を付与します。
  5. リポジトリのリレー設定に従ってモデルリレーを起動します。
  6. エージェントの起動時にリレーURLを設定します。
MODEL_RELAY=http://127.0.0.1:3099

OpenRouterのキーをソースコード、シェルスクリプト、イベントログ、実行メタデータに貼り付けないでください。このプロジェクトはSecret Managerからキーを取得し、プロセスメモリ内に保持するよう設計されています。

ステップ3: サーバーとドラゴンオブザーバーを準備する

互換性のあるバニラMinecraft Java 1.16.5サーバーJARをserver/server.jarに配置します。READMEには、インストール済みのMinecraft Javaランタイムでこのサーバーを実行できると記載されています。

ドラゴンオブザーバーはobserver/DragonObserver.javaに実装されています。次のコマンドでビルドします。

./build-observer.sh

メインサーバーと読み取り専用センサーを次のコマンドで起動します。

./start-server.sh

オブザーバーは、サーバーのドラゴンティックにローカル専用の観測呼び出しを追加します。読み取り専用のままにする必要があり、ドラゴンAIやプレイヤーまたはエンティティの状態を変更することはありません。

完全に新しいワールドを作成する

新しい実行ディレクトリを作成しても、Minecraftワールドはリセットされません。新しい記録を開始する前に、サーバーを停止し、server/server.propertiesで未使用のlevel-nameを選択します。設定済みのシードは変更せず、サーバーを再起動します。

実行ログディレクトリにも同じ新しい名前を使用します。以前のワールドが過去の実行の証拠を構成している場合は、それらを保持してください。

ステップ4: ネイティブクライアントをインストールしてビルドする

非表示のネイティブクライアントは、新しい記録で使用される公式Minecraftレンダリングを提供します。Python側の依存関係をインストールし、表示およびキャプチャアダプターをビルドします。

python3 native-client/install.py
./native-client/build.sh

クライアントは分離されたゲームディレクトリを使用するため、ユーザーの通常のMinecraft設定を上書きしません。デスクトップのフォーカスとカーソル制御は無効になっており、キャプチャはデスクトップではなくゲームのフレームバッファから読み取られます。

ステップ5: 実行設定を固定する

一意の識別子を選択します。以下ではNEW_RUNとして表します。エージェントを起動する前に、実行を固定します。

node optimization/nether/freeze-run.mjs NEW_RUN

最終ルートはoptimization/nether/config.jsonで定義されています。実行を固定すると、その実行で生成されるログと記録に関連付けられた設定を保持しやすくなります。

ステップ6: エージェントを起動する

リポジトリのルートからエージェントを起動します。次のコマンドはAstraを選択し、ネイティブビューとレコーダーを有効にして、ネイティブクライアントの起動を待機し、ドラゴンセンサーに接続します。

PLANNER_MODEL=openai/gpt-6-astra RUN_ID=NEW_RUN \
NATIVE_VIEW=1 WAIT_NATIVE=1 NATIVE_RECORD=1 \
DRAGON_SENSOR_URL=http://127.0.0.1:3093 node nether-agent.mjs

リレーURLがまだプロセス環境に設定されていない場合は、次のように追加します。

MODEL_RELAY=http://127.0.0.1:3099 \
PLANNER_MODEL=openai/gpt-6-astra RUN_ID=NEW_RUN \
NATIVE_VIEW=1 WAIT_NATIVE=1 NATIVE_RECORD=1 \
DRAGON_SENSOR_URL=http://127.0.0.1:3093 node nether-agent.mjs

プランナーとしてSolを使用するには、モデル値を変更します。

PLANNER_MODEL=openai/gpt-5.6-sol

ステップ7: 非表示のMinecraftクライアントを起動する

ローカルプロトコルミラーがポート25578で待ち受けるまで待ちます。その後、別のターミナルを開いて次を実行します。

python3 native-client/launch.py

WAIT_NATIVE=1が有効になっているため、エージェントは最初のアクションを実行する前に、非表示のクライアントとレコーダーを待機します。レコーダーはエンドポータルイベントの後に停止します。

生成されるキャプチャは、音声なし、960 × 540の解像度、毎秒20フレーム向けに設計されています。体力、満腹度、ホットバー、手に持っているアイテム、インベントリとクラフト画面、ネイティブアニメーション、ドラゴンの体力を表示できます。

実行を安全に監視して停止する

現在の状態は、ローカルステータスエンドポイントから確認できます。

http://127.0.0.1:3078

現在の進行状況はstatus.jsonにも書き込まれます。アクションの境界で停止を要求するには、次のファイルを作成します。

runs/NEW_RUN/stop

実行終了後、ネイティブクライアントをすぐに終了しないでください。記録完了マーカーを待ちます。

runs/NEW_RUN/full-playthrough.mp4.finished.json

これにより、最終キャプチャの途中切れや破損を防ぎやすくなります。

生成された証拠を理解する

各実行の証拠はruns/<run>に保存されます。主なファイルは次のとおりです。

  • events.jsonl: リクエスト、モデルの応答、選択されたアクション、ゲーム結果、完了イベント。
  • status.json: 実行の最新の進行状況。
  • victory.json: 必要なドラゴン死亡およびエンドポータルの証拠が存在する場合にのみ生成されます。
  • full-playthrough.mp4: 記録が有効な場合のネイティブ記録。
  • full-playthrough.mp4.finished.json: 記録の最終処理が完了したことを示す確認ファイル。

ドラゴン死亡の証拠には、キル進捗またはサーバーから報告された体力ゼロと、ドラゴンの死亡フェーズの組み合わせを使用できます。この区別は、ベッドによるキルではキル進捗が記録されない場合があるため重要です。Java 1.16.5では、退出イベントに数値理由4を使用します。

有効な最終レビューでは、victory.jsonだけに依存しないでください。ワールドのDragonFight状態と動画も確認する必要があります。

自動チェックを実行する

完了イベント、ネイティブミラーパケット、アクションポリシー、パスファインダーのキャンセルを確認するには、リポジトリのNodeテストスイートを使用します。

node --test evidence.test.mjs native-mirror.test.mjs optimization/*.test.mjs optimization/pass-2/policy.test.mjs optimization/nether/*.test.mjs

これらのテストは、実環境での検証に代わるものではありません。移動、クラフト、戦闘、サーバー統合、録画については、稼働中のMinecraftサーバーに対するテストが引き続き必要です。

エンドでの戦闘の仕組み

end-combat.mjsの戦闘実装は、JEVが選択できる、範囲を限定したベッド攻撃を1つ公開します。このアクションはベッドを1つ設置し、そこに照準を合わせ、観測されたドラゴンの頭部が設定された攻撃ウィンドウに入るまで待機してから、使用コマンドを1回送信します。

プレイヤーが遮蔽物を失った場合、またはドラゴンのブレスが遮蔽エリアに入った場合、アクションは中止されます。READMEによると、使用前に照準を合わせ、攻撃ウィンドウを狭めることで、ベッド1個あたりのダメージが11から46に向上しました。

最終検証済みの実行では、最初の着地時に6回のベッド爆発でドラゴンを倒しました。ただし、ドラゴンの飛行および着地のタイミングは実行ごとに異なるため、同じ完了時間が保証されるわけではありません。

戦闘ラボを正しく使用する

combat-labディレクトリは、独立したテスト環境です。準備済みの位置やインベントリなど、その他のテスト用変更を使用する場合があります。ハードコードされたドライバーであるcombat-probe.mjsは、ポート25577を使用し、どちらのモデルも呼び出しません。

戦闘ラボの結果を、モデルが完全に制御したサバイバル実行の結果として提示してはいけません。ラボの結果で検証できるのは分離された戦闘動作であり、空のインベントリから始まる完全なルートではありません。

高度な録画と検証のヒント

情報オーバーレイを追加して検証する

リポジトリには、モデル名、経過ミリ秒、XYZ座標、プランナーの目標、選択されたアクションを表示する半透明の上部バナーを追加するオーバーレイ手順が記載されています。これらのラベルは、記録されたモデルの応答とゲームイベントに基づいています。

記載されている実行例では、次のコマンドでオーバーレイを作成して検証します。

node overlay.mjs nether-final-02
node verify-run.mjs nether-final-02 nether-final-02 full-playthrough-overlay.mp4

以前のPrismarine Viewer録画では、記載されているコマンドは次のとおりです。

node assemble-video.mjs recorded-06
node verify-run.mjs recorded-06

以前のrecorded-06ワークフローでは、Prismarine ViewerとカスタムHUDを使用していました。新しい録画では、読み取り専用プロトコルミラーを介して、公式のMinecraft Java 1.16.5クライアントを使用します。

一時停止とコード更新履歴を保持する

エージェントにコード更新が必要だったために録画に複数のキャプチャファイルが含まれる場合は、すべてのアクティブなゲームプレイ区間を保持します。結合した動画内で各更新時の一時停止を示し、すべての死亡と一時停止を報告してください。その説明が正確でない限り、その実行を中断なし、または死亡なしと表現してはいけません。

危険なポータル進入戦略を避ける

ラボテストでは、エンドポータルへの長い落下によって落下ダメージがエンドに持ち越される可能性が示されました。録画されたルートではこの戦略を採用せず、短く確認しながら下向きに採掘する手順を使用しました。ルートの動作を変更する場合も、この安全上の制約を維持してください。

勝利後は終了状態を維持する

現在の実装では、勝利後に別のゲームアクションを実行できないようになっています。アクションループを変更する場合も、この動作を維持してください。勝利後のアクションによって、ログや録画の解釈が難しくなる可能性があります。

ローカルの成果物をGitに含めない

録画と生成された証拠は、意図的にローカルに保持されます。最新動画の記載されたパスはruns/nether-final-08/full-playthrough-banner.mp4で、検証結果、タイミング比較、アクションログは同じ実行ディレクトリにあります。録画、ダウンロードしたランタイム、サーバーバイナリ、ワールド、認証情報をコミットしないでください。

トラブルシューティングチェックリスト

  • エージェントが開始しない: ミラーがポート25578で待ち受けており、ネイティブクライアントが接続済みであることを確認します。WAIT_NATIVE=1の場合、待機は想定された動作です。
  • モデルリクエストが失敗する: Google Application Default Credentials、Secret Managerの権限、model-relay.mjsとmodels.mjs内のプロジェクトおよびシークレット参照、ポート3099でのリレーの可用性、OpenRouterのクレジットを確認します。
  • 実行が古いワールドで開始される: サーバーを停止し、実際に未使用のlevel-nameを設定します。新しい実行ディレクトリを作成するだけでは不十分です。
  • ドラゴンの観測結果を取得できない: オブザーバーをビルドし、そのセンサー付きでサーバーを起動して、エージェントがDRAGON_SENSOR_URL=http://127.0.0.1:3093を使用していることを確認します。
  • 録画完了マーカーが表示されない: full-playthrough.mp4.finished.jsonが書き込まれるまで、ネイティブクライアントを実行したままにします。
  • プラットフォーム固有のパスで失敗する: 提供されたスクリプトはmacOS上で開発されたため、Java、Minecraftランタイム、ネイティブクライアント、サーバーのパスを調整します。

結論

AstraとJEVのプロジェクトは、無制限のゲームボットではなく、構造化され証拠を重視したMinecraftエージェントを示しています。AstraまたはSolがルートを計画し、JEVが範囲を限定したアクションを選択し、Mineflayerが通常のプロトコルを通じて実行し、読み取り専用センサーが正確なドラゴン戦闘を支援します。信頼できる実行には、認証情報の慎重な取り扱い、真に新しいワールド、同期されたネイティブ録画、保持されたログ、自動テスト、そしてゲーム状態と動画証拠の両方に対する最終レビューが必要です。

関連する基盤については、TypeSafe公式の紹介記事、Mineflayerリポジトリ、およびAstraモデルの公式ドキュメントをご覧ください。