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

Agent Office 3D チュートリアル：AIコーディングエージェントを3Dオフィスの社員にする

このチュートリアルでは、Agent Office 3Dのインストール、デモオフィスの起動、会社と社員データの設定を行い、さらにHerdrとの接続やMinecraftの選択、エージェントの状態、ターミナル出力、安全設定について説明します。

約14分で読了
Agent Office 3D チュートリアル：AIコーディングエージェントを3Dオフィスの社員にする

Agent Office 3D とは？

Agent Office 3D は、ローカル環境で動作するローポリゴンの 3D オフィスです。AI Coding Agent をオフィスで働く従業員として表示します。各 Agent が作業中、アイドル、完了して待機中、または確認が必要な権限プロンプトで停止しているかを一目で確認できます。

プロジェクトはデフォルトでデモデータを使用するため、最初に Agent を接続する必要はありません。アイドル状態の従業員は、コーヒーを入れる、水を飲む、トレッドミルを使う、ストレッチをする、居眠りをする、内蔵ミニゲームで遊ぶといった行動をします。Minecraft を有効にすると、従業員は Mineflayer ボットを使ってローカルワールドに入ることもできます。

画面上の従業員、タスク、プロジェクト、金額はすべてデモデータであり、実際の業務情報ではありません。

主な機能

  • リアルタイムの従業員ステータス：各 Agent には専用の席、ステータスランプ、ネームプレートがあります。確認が必要な場合は、赤いネームプレートと感嘆符で通知します。
  • 読み取り専用のターミナル画面：従業員をクリックすると直近のターミナル出力を確認できますが、オフィス画面からコマンドを送信することはできません。
  • 掲示板：年間目標、KPI、今週の重点項目、キャッシュフロー、ToDo リストを表示します。ToDo はその場でチェックできます。
  • 本棚のプロジェクトデータベース：各本が 1 つのプロジェクトフォルダに対応しており、Markdown ドキュメントやスクリーンショットを閲覧できます。
  • タスクリスト：右側からタスクフォルダ内のファイルと全文を確認できます。
  • Minecraft の休憩アクティビティ：アイドル状態の従業員は、それぞれの Mineflayer ボットで採掘、伐採、建築を行います。デスクのモニターには一人称視点が表示されます。

掲示板ホーム：キャッシュフローと年間目標

掲示板をクリックすると、会社データと ToDo を確認できる全画面インターフェースが開きます。

本棚：プロジェクトデータベース

本棚では読み取り専用でプロジェクトを閲覧でき、ドキュメントやプロジェクト素材をすばやく確認できます。

動作環境

  • Node.js 20 以上：オフィスを実行するための必須条件です。
  • Java 21 以上：​​Minecraft 機能を有効にする場合のみ必要です。
  • WebGL 対応ブラウザ：Chrome、Edge、Safari、Firefox に対応しています。

主な対応プラットフォームは macOS と Linux です。Windows は現在実験的な対応で、CI ではインストール、構文チェック、デモモードのテストを実行しますが、作者は実機の Windows 環境で検証しておらず、Minecraft も Windows 上ではまだ実機検証されていません。

インストールとデモオフィスの起動

macOS と Linux

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

Windows PowerShell

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

起動すると、プログラムは http://127.0.0.1:4870/ を開きます。デフォルトでは demo モードが使用され、従業員のステータスが自動的に切り替わるため、事前に Agent を準備したり接続したりする必要はありません。体験を終えたら、ターミナルで Ctrl+C を押すと停止できます。

AI Coding Agent を使ったインストール

Claude Code、Codex、Cursor などの AI Coding Agent を使用している場合は、まずプロジェクトフォルダで起動し、次の指示を貼り付けることもできます。

この repo の AGENTS.md を読んで、Agent Office をインストールし、Minecraft のデモを起動してください。

Agent は AGENTS.md に従って npm run doctor を実行し、インストールとデモの起動を支援します。また、Herdr に接続するかどうかや、会社と従業員をどのようにカスタマイズするかを確認します。Node.js や Java などのシステムソフトウェアをインストールする前には、先に確認を求めます。Minecraft EULA については、あなた自身が読み、yes を入力する必要があり、AI Agent が代わりに同意することはありません。Claude Code のユーザーは /setup-office と入力することもできます。

会社、従業員、データソースの設定

まずサンプル設定ファイルをコピーします。

cp office.config.example.json office.config.json

Windows PowerShell では次を使用できます。

Copy-Item office.config.example.json office.config.json

office.config.json はバージョン管理に含まれません。ファイルが存在しない場合、プログラムはサンプル設定を直接使用します。主なフィールドは次のとおりです。

  • port：サービスのポート。デフォルトは 4870 です。
  • openBrowser：起動後にブラウザを自動で開くかどうか。
  • company.name：タイトルバーと会社の看板に表示する名前。
  • company.currency：掲示板に表示する通貨記号。$ や NT$ など。
  • company.logo と company.mark：会社の横長 Logo と小さなアイコンのパス。
  • owner.name、owner.title：管理者デスクの人物の名前と役職。管理者デスクは装飾用で、Agent のステータスは受け取りません。
  • cat.name：オフィスの猫の名前。
  • staff[]：従業員リスト。id、title、制服の color を含み、最大 8 人まで。
  • source.type：ステータスのソース。demo または herdr を指定できます。
  • data.board、data.projects、data.tasks：掲示板、プロジェクト、タスクデータの場所。

従業員の staff[].id は、ステータスソースにある Agent 名と一致している必要があります。掲示板と本棚のデータ形式については、docs/board-format.md を参照してください。

実際の Agent に接続する：Herdr モード

Herdr は Coding Agent 向けのターミナルマルチプレクサです。Herdr に接続するには、まず Herdr で Agent を起動し、設定を変更します。

{
  "source": {
    "type": "herdr"
  },
  "staff": [
    {
      "id": "あなたの Herdr Agent 名",
      "title": "役職",
      "color": "#4f8cff"
    }
  ]
}

続いて実行します。

npm start

オフィスが Herdr に呼び出すのは、読み取り専用コマンドの herdr agent list と herdr agent read のみです。組み込みの許可リストによってその他のコマンドはブロックされるため、オフィスがキー入力を送信したり、権限確認を代わりに押したりすることはありません。

別のステータスツールに接続する場合は、lib/sources.js に adapter を追加し、名前、ステータス、ターミナル出力の末尾数行を含む同じ形式の従業員リストを返すようにしてください。

Minecraft デモを有効にする

デモの従業員が Minecraft をプレイする様子をすぐに見たい場合は、次を実行します。

npm run demo:minecraft

この機能には Node.js 20 以上と Java 21 以上が必要です。初回実行時には Java のチェック、Minecraft EULA の読了と同意の確認、Mojang 公式バージョンリストからの 1.21.4 サーバーファイルのダウンロード、SHA-1 の検証が行われます。ワールドの作成には通常約 1～2 分かかります。

eula=true を書き込むには、本人が yes と入力する必要があります。それ以外を入力すると処理はキャンセルされ、Mojang のファイルもダウンロードされません。これは Minecraft サーバーソフトウェアの EULA に、実際に実行する本人が同意する必要があるためです。

通常のオフィスモードで Minecraft を有効にするには、まず次を実行します。

npm run minecraft:setup

完了後、設定ファイルの minecraft.enabled を true に変更し、npm start を実行します。Minecraft サーバーは 127.0.0.1 にバインドされ、ホワイトリストで接続を制限します。従業員が仕事に戻ると、対応するボットは活動を停止します。従業員がアイドル状態で、誰かがオフィス画面を開いている場合にのみボットが動作します。

掲示板ホーム：キャッシュフローと年間目標

Minecraft ゲーム内から従業員を見る

Minecraft Java 版を所有している場合は、自分のプレイヤー名を minecraft.guests に追加できます。

{
  "minecraft": {
    "guests": ["YourName"]
  }
}

環境変数を使用することもできます。

MC_GUESTS=YourName npm run demo:minecraft

Windows PowerShell では次を使用できます。

$env:MC_GUESTS="YourName"; npm run demo:minecraft
  1. 同じコンピューターで Minecraft Java 版 1.21.4 を起動します。
  2. マルチプレイに入り、「ダイレクト接続」を選択して localhost:25570 を入力します。
  3. 入場後、自動的にスペクテイターモードに切り替わり、ワールドを変更せずに飛行や壁抜けができます。
  4. 数字キー 1 を押すかマウスの中ボタンを使ってスペクテイターメニューを開き、従業員を選択して観察します。

設定したプレイヤー名はボットとともにホワイトリストに追加され、他のプレイヤーは接続できません。サーバーはオフラインモードで動作し、ローカルホストのみをリッスンします。バインドアドレスを変更したり、外部に公開したりしないでください。

開発と診断コマンド

プロジェクトには、環境の確認と変更の検証に適したコマンドがいくつか用意されています。

npm run doctor  # 読み取り専用の環境チェック
npm run check   # JavaScript の構文と JSON 形式をチェック
npm run smoke   # デモモードのスモークテスト

npm run doctor はすべての項目が準備できている場合に終了コード 0 を返します。Minecraft の準備ができていない場合は 2、オフィスを実行できない場合は 1 を返します。-- --json を追加すると、JSON 形式で結果を出力できます。

開発時にはURLパラメータも使用できます。たとえば、?fast で動作を高速化し、?idle=coffee でアイドル状態の従業員に指定した動作を実行させ、?cat=nap で猫のスケジュールを調整できます。使用できる動作名は public/behavior.js を参照してください。

安全に関する注意事項

  • オフィスはAgentのターミナル出力を読み取ります。そこにはコード、パス、機密情報が含まれる場合があります。
  • サーバーは 127.0.0.1 にのみバインドされ、Hostヘッダーを検証します。リバースプロキシ、トンネル、公開ネットワーク経由でサービスを公開しないでください。
  • オフィスで唯一の書き込み機能は、掲示板のToDo項目にチェックを付けることです。その他のAgentの状態とターミナルデータはすべて読み取り専用です。
  • 本棚は設定されたフォルダのみを読み取り、パストラバーサルやディレクトリ外へ移動するシンボリックリンクを防止します。それでも、プロジェクトフォルダにパスワードやトークンを置くことは推奨しません。
  • Minecraftサーバーはローカルでのみ待ち受け、ホワイトリストを有効にしています。外部接続用に変更しないでください。

まとめ

Agent Office 3Dは、もともとターミナルに分散していたAgentの状態を、理解しやすい3Dオフィスに変換します。まず npm start でデモモードを体験し、次に office.config.json で会社や従業員をカスタマイズし、最後にHerdrへ接続して実際のAgentの状態を確認できます。インタラクティブ性を高めたい場合は、npm run demo:minecraft を使って、アイドル状態の従業員がローカルのMinecraftワールドで活動する様子を確認できます。

このプロジェクトはMIT Licenseでライセンスされており、MojangまたはMicrosoftとは関係がないことを覚えておいてください。Minecraftを使用する場合は、各自でそのEULAを読み、同意する必要があります。