ホステッドエージェントインフラストラクチャ
ホステッドエージェントは、ローカルマシンではなくリモートのサンドボックス環境で実行されます。適切に設計すると、無制限の同時実行性、一貫性のある実行環境、およびマルチプレイヤーコラボレーションを提供します。重要な洞察は、セッション速度はモデルプロバイダーの最初のトークンまでの時間によってのみ制限され、ユーザーがセッションを開始する前にすべてのインフラストラクチャセットアップが完了している必要があることです。
アクティブ化のタイミング
以下の場合にこのスキルをアクティブ化します：
- ユーザーデバイスから独立して実行されるバックグラウンドコーディングエージェントを構築する場合
- エージェントワークロード用のサンドボックス実行環境を設計する場合
- 共有状態を持つマルチプレイヤーエージェントセッションを実装する場合
- マルチクライアントエージェントインターフェース（Slack、Web、Chrome拡張機能）を作成する場合
- ローカルマシンの制約を超えてエージェントインフラストラクチャをスケーリングする場合
- エージェントが並行作業のためにサブエージェントを生成するシステムを構築する場合
他のスキルが担当する隣接作業ではこのスキルをアクティブ化しないでください：
- 自律研究ループ、ノベルティゲート、ロールバックポリシー、マージ境界の設計：
harness-engineering - ホステッドインフラストラクチャの懸念がないスーパーバイザー、スウォーム、またはハンドオフトポロジの選択：
multi-agent-patterns - ホステッドエージェントが使用するツール（spawn/statusツールやPRツールなど）の設計：
tool-design - ホステッドランタイム自体ではなく、セッション内のファイルバック状態の管理：
filesystem-context
コアコンセプト
エージェントの実行をリモートのサンドボックス環境に移行して、ローカル実行の基本的な制限（リソース競合、環境の不一致、シングルユーザー制約）を排除します。リモートサンドボックスは、各セッションが既知の良好な環境イメージで独自の分離されたコンピュートを取得するため、無制限の同時実行性、再現可能な環境、およびコラボレーティブワークフローを実現します。
各レイヤーが独立してスケーリングするため、アーキテクチャを3つのレイヤーで設計します。分離された実行のためのサンドボックスインフラストラクチャ、状態管理とクライアント調整のためのAPIレイヤー、およびプラットフォーム間でのユーザーインタラクションのためのクライアントインターフェースを構築します。これらのレイヤーを明確に分離して、サンドボックスの変更がクライアントに波及しないようにします。
詳細トピック
サンドボックスインフラストラクチャ
中核的な課題 サンドボックスのスピンアップレイテンシを排除します。なぜなら、ユーザーは数秒以上かかると壊れていると認識するからです。開発環境では、リポジトリのクローン、依存関係のインストール、ビルド手順の実行が必要です。これらはすべて、ユーザーがプロンプトを送信する前に実行します。
イメージレジストリパターン 環境イメージを定期的な周期（30分ごとが適切）で事前構築します。これにより、最新のコードとの同期がフルクローンではなく高速な差分になります。各イメージに以下を含めます：
- 既知のコミットでクローンされたリポジトリ
- インストールされたすべてのランタイム依存関係
- 完了した初期セットアップとビルドコマンド
- アプリとテストスイートを1回実行したときのキャッシュされたファイル
セッションを開始するときは、最新のイメージからサンドボックスをスピンアップします。リポジトリは最大30分古いため、残りのgit同期は高速です。
スナップショットと復元 主要なポイントでファイルシステムスナップショットを取得して、セットアップを再実行せずにフォローアッププロンプトのインスタント復元を可能にします：
- 初期イメージ構築後（ベーススナップショット）
- エージェントが変更を完了したとき（セッションスナップショット）
- 潜在的なフォローアップのためにサンドボックスを終了する前
バックグラウンドエージェントのGit設定 すべてのサンドボックスでgit IDを明示的に設定します。なぜなら、バックグラウンドエージェントはイメージ構築中に特定のユーザーに結びついていないからです：
- クローン中にリポジトリにアクセスするためのGitHubアプリインストーラートークンを生成します
- コミットとプッシュ時に
user.nameとuser.emailのgit設定を行います - コミットにはアプリIDではなくプロンプトを送信したユーザーのIDを使用します
ウォームプール戦略 高ボリュームのリポジトリ用に事前ウォームされたサンドボックスのプールを維持します。なぜなら、コールドスタートがユーザーの不満の主な原因だからです：
- ユーザーがセッションを開始する前にサンドボックスを準備しておきます
- 新しいイメージビルドが完了するにつれて、プールエントリを期限切れにして再作成します
- ユーザーが入力を開始するとすぐにサンドボックスのウォームアップを開始します（予測的ウォームアップ）
エージェントフレームワークの選択
サーバーファーストアーキテクチャ エージェントフレームワークをまずサーバーとして構成し、TUIやデスクトップアプリはシンクライアントとします。これにより、エージェントロジックがさまざまな表面で複製されるのを防ぎます：
- 複数のカスタムクライアントが1つのエージェントバックエンドを共有します
- すべてのインタラクション表面で一貫した動作
- プラグインシステムはクライアントの変更なしで機能を拡張します
- イベント駆動型アーキテクチャは、接続された任意のクライアントにリアルタイム更新を配信します
コードをソースオブトゥルースとして エージェントが自身のソースコードを読み取って動作を理解できるフレームワークを選択します。これを優先します。なぜなら、コードをソースオブトゥルースとすることで、エージェントが自身の能力について幻覚を見るのを防ぐからです。これはAI開発における過小評価されている障害モードです。
プラグインシステムの要件 ランタイムインターセプションをサポートするプラグインシステムを要求します。これにより、コアエージェントロジックを変更せずに安全性制御と可観測性が可能になります：
- ツール実行イベントをリッスンします（例：
tool.execute.before） - 条件付きでツール呼び出しをブロックまたは変更します
- ランタイムでコンテキストまたは状態を注入します
速度最適化
予測的ウォームアップ ユーザーがプロンプトを送信したときではなく、入力を開始したときにサンドボックスのウォームアップを開始します。なぜなら、入力間隔（5〜30秒）はほとんどのセットアップを完了するのに十分だからです：
- ユーザーの入力と並行して最新の変更をクローンします
- ユーザーがEnterキーを押す前に初期セットアップを実行します
- 高速スピンアップの場合、ユーザーが入力を終える前にサンドボックスを準備できます
並行ファイル読み取り 最新のベースブランチからの同期が完了していなくても、エージェントがすぐにファイルの読み取りを開始できるようにします。なぜなら、大規模リポジトリでは、受信プロンプトが最近変更されたファイルに触れることはめったにないからです：
- エージェントはgit同期を待たずにすぐに調査できます
- 同期が完了するまでファイル編集（読み取りではない）をブロックします
- 読み取り時のデータの30分の古さは調査にはほとんど問題にならないため、この分離は安全です
ビルド時作業の最大化 可能な限りすべてをイメージビルドステップに移動します。なぜなら、ビルド時の所要時間はユーザーには見えないからです：
- 完全な依存関係のインストール
- データベーススキーマのセットアップ
- 初期アプリとテストスイートの実行（キャッシュの事前入力）
自己生成エージェント
エージェントが生成するセッション エージェントが新しいセッションを生成できるツールを構築します。なぜなら、フロンティアモデルは作業を分解し、サブタスクを調整できるからです：
- 異なるリポジトリにわたる研究タスク
- 大規模な変更に対する並行サブタスク実行
- 1つの主要タスクからの複数の小さなPR
3つのプリミティブを公開します：指定されたパラメータで新しいセッションを開始する、任意のセッションのステータスを読み取る（チェックイン機能）、サブセッションが並行して実行されている間、メインの作業を続行する。
自己生成のためのプロンプトエンジニアリング エージェントがインラインで作業を行うのではなく、いつサブセッションを生成すべきかをガイドするプロンプトを設計します：
- リポジトリ間の探索を必要とする研究タスク
- モノリシックな変更をより小さなPRに分割する
- 異なるアプローチの並行探索
APIレイヤー
セッションごとの状態分離 セッションごとに状態を分離します（SQLiteはセッションごとに適切に機能します）。なぜなら、セッション間の干渉は微妙でデバッグが難しい障害モードだからです：
- セッションごとに専用のデータベース
- あるセッションが別のセッションのパフォーマンスに影響を与えることはできません
- アーキテクチャは数百の同時セッションを処理します
リアルタイムストリーミング すべてのエージェント作業をリアルタイムでストリーミングします。なぜなら、高頻度のフィードバックはユーザーの信頼にとって重要だからです：
- モデルプロバイダーからのトークンストリーミング
- ツール実行ステータスの更新
- ファイル変更通知
WebSocket接続をハイバネーションAPIとともに使用して、アイドル期間中のコンピュートコストを削減しながら、開いている接続を維持します。
クライアント間の同期 すべてのクライアント（チャットインターフェース、Slackボット、Chrome拡張機能、Webインターフェース、VS Codeインスタンス）間で同期する単一の状態システムを構築します。なぜなら、ユーザーは頻繁に表面を切り替え、継続性を期待するからです。すべての変更がセッション状態に同期され、シームレスなクライアント切り替えが可能になります。
マルチプレイヤーサポート
マルチプレイヤーが重要な理由 初日からマルチプレイヤー向けに設計します。なぜなら、適切な同期アーキテクチャを使用すれば追加はほぼ無料であり、高価値のワークフローを実現するからです：
- 非エンジニアにAIを効果的に使用する方法を教える
- 複数のチームメンバーによるライブQAセッション
- 即時変更によるリアルタイムPRレビュー
- 共同デバッグセッション
実装要件 セッションが単一の作成者に結びつかないようにデータモデルを構築します。なぜなら、作成者がハードコードされているとマルチプレイヤーはサイレントに失敗するからです：
- 各プロンプトに作成者情報を渡します
- コード変更をプロンプト送信ユーザーに帰属させます
- インスタントコラボレーションのためのセッションリンクを共有します
認証と認可
ユーザーベースのコミット GitHub認証を使用して、アプリではなくユーザーに代わってPRを開きます。これにより、監査証跡が保持され、ユーザーが自分自身のAI生成変更を承認するのを防ぎます：
- PR作成のためにユーザートークンを取得します
- PRはボットではなく人間が作成したように表示されます
サンドボックスからAPIへのフロー このシーケンスに従います。なぜなら、サンドボックスの権限を最小限に抑えながら、APIが機密操作を処理できるようにするからです：
- サンドボックスが変更をプッシュします（gitユーザー設定の更新）
- サンドボックスがブランチ名とセッションIDを含むイベントをAPIに送信します
- APIがユーザーのGitHubトークンを使用してPRを作成します
- GitHub webhookがPRイベントをAPIに通知します
クライアント実装
Slack統合 内部採用のための最初の流通チャネルとしてSlackを優先します。なぜなら、チームメンバーが他の人が使用しているのを見ると、バイラリティループが生まれるからです：
- 構文不要、自然なチャットインターフェース
- どのリポジトリで作業するかを決定するための分類器（リポジトリ説明を含む高速モデル）を構築します
- 一般的なリポジトリのヒントを含めます。曖昧な場合は「不明」を許可します
Webインターフェース 以下の機能を備えたWebインターフェースを構築します。なぜなら、これが主要なパワーユーザーサーフェスとして機能するからです：
- デスクトップとモバイルでのエージェント作業のリアルタイムストリーミング
- サンドボックス内で実行されるホステッドVS Codeインスタンス
- 視覚的検証のためのストリーミングデスクトップビュー
- PRの前後スクリーンショット
- 統計ページ：マージされたPRにつながったセッション（主要指標）、経時的な使用状況、ライブの「人間がプロンプトを送信中」のカウント
Chrome拡張機能 非エンジニアリングユーザー向けにChrome拡張機能を構築します。なぜなら、DOMとReactの内部構造を抽出すると、生のスクリーンショットよりも低いトークンコストで高い精度が得られるからです：
- スクリーンショットツールを備えたサイドバーチャットインターフェース
- 生の画像ではなく、DOM/Reactの内部構造を抽出します
- 管理デバイスポリシーを介して配布します（Chrome Web Storeをバイパスします）
実践的なガイダンス
ホステッドエージェント設計チェックリスト
システムを構築する前に、これらのインフラストラクチャプロパティを明示的に決定します：
- サンドボックスライフサイクル：セッションの開始、スナップショット、復元、タイムアウト、終了方法。
- イメージとウォームプールポリシー：イメージの再構築頻度、事前計算されるキャッシュ、ウォームサンドボックスの有効期限。
- 読み取り/書き込み同期：エージェントがリポジトリ同期の完了前に読み取りを許可されるかどうか、および書き込みのブロックを解除するイベント。
- セッションごとの状態分離：どのストレージが1つのセッションに属するか、何が共有されるか、セッション間の干渉を防ぐ方法。
- 認証とコミットID：どの操作がアプリトークンを使用するか、どの操作がユーザートークンを使用するか、コミットの帰属方法。
- 出力抽出：ブランチ、PR、ファイル、ログ、スクリーンショット、セッションサマリーがサンドボックスを離れる方法。
- 予算とティアダウン：最大実行時間、コスト上限、アイドルポリシー、強制クリーンアップ動作。
フォローアップメッセージの処理
実行中に送信されたフォローアップメッセージをキューイングするか挿入するかを選択します。キューイングは管理がより簡単で、エージェントが作業中にユーザーが次のステップについて考えを送信できるようにするため、キューイングを推奨します。必要に応じてエージェントを実行中に停止するメカニズムを構築します。これがないと、ユーザーは閉じ込められたように感じます。
重要な指標
これらの指標を追跡します。これらは、単なる見せかけの使用ではなく、実際の価値を示すためです：
- マージされたPRにつながったセッション（主要な成功指標）
- セッション開始から最初のモデル応答までの時間
- PR承認率とリビジョン数
- リポジトリ全体のエージェント作成コードの割合
採用戦略
強制ではなく可視性を通じて内部採用を促進します。なぜなら、強制された使用は不満を生むからです：
- 可視性のために公共スペース（Slackチャンネル）で作業します
- 製品にバイラリティループを作らせます
- 既存のツールよりも強制的に使用させないようにします
- 仮説的な要件ではなく、人々のニーズに基づいて構築します
例
例1：バックグラウンドコーディングセッションのライフサイクル
ユーザープロンプト
-> APIが現在のイメージからウォームサンドボックスを割り当てます
-> サンドボックスが最新のブランチ差分を同期します
-> 読み取りは即座に許可され、同期が完了するまで書き込みはブロックされます
-> エージェントが分離されたワークスペース内で編集とテストを行います
-> サンドボックスが最終的なファイルシステムのスナップショットを取得します
-> ブランチがプッシュされます
-> APIがユーザートークンを使用してPRを作成します
-> セッションサマリー、ログ、PR URLがクライアントに返されます
このシーケンスは、監査可能性とコード変更のユーザー所有権を維持しながら、セットアップ作業をユーザーに見えないパスの外に保ちます。
例2：境界の決定
タスクが「ロックされたルーブリックとPR承認を使用してエージェントループを何日も実行させる」ことである場合は、harness-engineeringを使用します。タスクが「そのループをリモートサンドボックスでウォームプール、セッションスナップショット、ストリーミングクライアント、ユーザー作成PRとともに実行する」ことである場合は、このスキルを使用します。
ガイドライン
- 定期的な周期（30分が適切なデフォルト）で環境イメージを事前構築します
- ユーザーが送信するときではなく、入力を開始したときにサンドボックスのウォームアップを開始します
- git同期が完了する前にファイルの読み取りを許可します。書き込みのみブロックします
- エージェントフレームワークをサーバーファーストとして構成し、クライアントはシンラッパーとします
- セッション間の干渉を防ぐために、セッションごとに状態を分離します
- コミットはアプリではなく、プロンプトを送信したユーザーに帰属させます
- マージされたPRを主要な成功指標として追跡します
- 初日からマルチプレイヤー向けに構築します。適切な同期アーキテクチャを使用すれば、ほぼ無料です
落とし穴
- コールドスタートレイテンシ：最初のサンドボックススピンアップには30〜60秒かかり、ユーザーはこれを壊れていると認識します。ウォームプールを使用します。
- ウォームプールの有効期限：ウォームプールのサンドボックスアイドルポリシーを設定しないと、すべてのサンドボックスがアイドル状態になり、コールドスタートに戻ります。
- 状態の漏洩：セッション間でのデータベースやファイルシステムの共有を防ぎます。各セッションは独自の分離された状態を持つ必要があります。
- gitの誤った設定：バックグラウンドエージェントは特定のユーザーに結びついていないため、git IDを明示的に設定しないと、コミットが匿名ユーザーに帰属します。
- 副作用のない読み取りの前提：ファイル読み取りのブロック解除は、読み取り操作に副作用がないことを前提としています。一部のファイルシステム操作（git statusなど）は書き込みとしてカウントされる場合があります。
- プラグインの欠如：プラグインシステムがないと、安全性制御と可観測性を実装するには、コアエージェントロジックのフォークが必要になり、保守が困難になります。
- 認証のボトルネック：ユーザートークンの取得は、スコープと同意プロセスによっては低速になる可能性があります。ウォームパス内で処理します。
- クライアントの状態の不一致：異なるクライアントが異なる状態を表示すると、ユーザーの混乱と信頼の喪失につながります。APIレイヤーをシングルソースオブトゥルースとして使用します。