hosted-agents

ホスト型エージェントインフラストラクチャ

ホスト型エージェントは、ローカルマシンではなく、リモートのサンドボックス環境で実行されます。適切に設計すれば、無制限の並行実行、一貫性のある実行環境、複数人での共同作業を実現できます。重要なのは、セッションの速度をモデルプロバイダーの最初のトークンが生成されるまでの時間だけで決まるようにし、ユーザーがセッションを開始する前に、すべてのインフラストラクチャのセットアップを完了しておくことです。

有効化する場面

次の場合に、このスキルを有効にしてください。

• ユーザーのデバイスから独立して実行されるバックグラウンドコーディングエージェントを構築する
• エージェントのワークロード向けに、サンドボックス化された実行環境を設計する
• 共有状態を持つ、複数人でのエージェントセッションを実装する
• 複数のクライアントに対応するエージェントインターフェース（Slack、Web、Chrome 拡張機能）を作成する
• ローカルマシンの制約を超えてエージェントインフラストラクチャをスケーリングする
• エージェントがサブエージェントを起動して並行作業を行うシステムを構築する

他のスキルが担当する、関連する作業ではこのスキルを有効にしないでください。

• 自律的な調査ループ、新規性の判定、ロールバックポリシー、マージ境界を設計する場合：harness-engineering。
• ホスト型インフラストラクチャに関する懸念を伴わずに、スーパーバイザー、スウォーム、ハンドオフのトポロジーを選択する場合：multi-agent-patterns。
• spawn/status ツールや PR ツールなど、ホスト型エージェントが使用するツールを設計する場合：tool-design。
• ホスト型ランタイム自体ではなく、セッション内のファイルベースの状態を管理する場合：filesystem-context。

コアコンセプト

エージェントの実行をリモートのサンドボックス環境に移し、リソースの競合、環境の不整合、シングルユーザーの制約といったローカル実行の根本的な限界を解消します。リモートサンドボックスでは、各セッションに既知の正常な環境イメージを備えた独立したコンピューティング環境を割り当てるため、無制限の並行実行、再現可能な環境、共同作業のワークフローを実現できます。

各レイヤーは独立してスケールするため、アーキテクチャを3つのレイヤーに分けて設計します。分離された実行環境のためのサンドボックスインフラストラクチャ、状態管理とクライアント連携のための API レイヤー、複数のプラットフォームでユーザーが操作するためのクライアントインターフェースを構築します。サンドボックスの変更がクライアントに波及しないよう、これらのレイヤーを明確に分離してください。

詳細なトピック

サンドボックスのインフラストラクチャ

主要な課題 サンドボックスの起動遅延をなくします。数秒を超えると、ユーザーは不具合だと感じるためです。開発環境では、リポジトリのクローン、依存関係のインストール、ビルド手順の実行が必要です。これらはすべて、ユーザーがプロンプトを送信する前に済ませておきます。

イメージレジストリのパターン イメージは定期的に（30 分ごとが適切です）事前ビルドします。こうすることで、最新のコードとの同期がフルクローンではなく、差分だけの高速処理になります。各イメージには次の内容を含めます。

• 既知のコミット時点でクローンされたリポジトリ
• インストール済みのすべてのランタイム依存関係
• 完了済みの初期セットアップとビルドコマンド
• アプリとテストスイートを一度実行してキャッシュしたファイル

セッションの開始時に、最新のイメージからサンドボックスを起動します。リポジトリの遅れは最大でも 30 分なので、残りの Git 同期は高速です。

スナップショットと復元 セットアップを再実行せずに、後続のプロンプトに対して即座に復元できるよう、重要な時点でファイルシステムのスナップショットを作成します。

• 初回のイメージビルド後（ベーススナップショット）
• エージェントが変更を完了したとき（セッションスナップショット）
• 後続の対応に備えたサンドボックスの終了前

バックグラウンドエージェント向けの Git 設定 イメージビルド中のバックグラウンドエージェントは特定のユーザーに紐づいていないため、各サンドボックスで Git の ID を明示的に設定します。

• クローン中のリポジトリアクセスには、GitHub アプリのインストールトークンを生成します
• 変更をコミットおよびプッシュする際に、user.name と user.email を Git に設定します
• コミットにはアプリの ID ではなく、プロンプトを送信したユーザーの ID を使用します

ウォームプール戦略 コールドスタートはユーザーの不満の主な原因となるため、利用頻度の高いリポジトリ向けに、事前にウォームアップしたサンドボックスのプールを維持します。

• ユーザーがセッションを開始する前に、サンドボックスを使用可能な状態にしておきます
• 新しいイメージのビルド完了に合わせて、プール内のエントリを期限切れにし、再作成します
• ユーザーが入力を始めたら、すぐにサンドボックスのウォームアップを開始します（予測ウォームアップ）

エージェントフレームワークの選定

サーバー優先のアーキテクチャ エージェントフレームワークは、まずサーバーとして構成し、TUI とデスクトップアプリは薄いクライアントとします。こうすることで、各種 UI 間でエージェントのロジックが重複するのを防げます。

• 複数のカスタムクライアントで、1 つのエージェントバックエンドを共有できます
• あらゆる操作 UI で一貫した動作を実現できます
• プラグインシステムにより、クライアントを変更せずに機能を拡張できます
• イベント駆動型アーキテクチャにより、接続中のあらゆるクライアントにリアルタイム更新を配信できます

信頼できる情報源としてのコード エージェントが自身のソースコードを読み、動作を把握できるフレームワークを選びます。これを優先することで、信頼できる情報源をコードとし、エージェントが自身の能力について幻覚を起こすのを防げます。これは AI 開発において、見過ごされがちな失敗要因です。

プラグインシステムの要件 ランタイムでの割り込みに対応するプラグインシステムを必須とします。これにより、エージェントの中核ロジックを変更せずに、安全制御と可観測性を実現できます。

• ツール実行イベント（例：tool.execute.before）をリッスンします
• 条件に応じてツール呼び出しをブロックまたは変更します
• 実行時にコンテキストや状態を注入します

速度の最適化

予測的なウォームアップ ユーザーがプロンプトを送信したときではなく、入力を始めた時点でサンドボックスのウォームアップを開始します。入力にかかる時間（5～30 秒）で、ほとんどのセットアップを完了できるためです。

• ユーザーが入力している間に、最新の変更を並行してクローンします
• ユーザーが Enter キーを押す前に、初期セットアップを実行します
• 起動を速めることで、ユーザーが入力を終える前にサンドボックスを準備できます

ファイルの並列読み込み 最新のベースブランチとの同期が完了していなくても、エージェントがすぐにファイルを読み始められるようにします。大規模なリポジトリでは、受信したプロンプトが最近変更されたファイルに触れることはまれなためです。

• Git の同期を待たずに、エージェントがすぐに調査を開始できます
• 同期が完了するまで、ファイルの編集はブロックします（読み込みはブロックしません）
• 調査では読み込み時のデータが 30 分古くても、ほとんど問題にならないため、この分離は安全です

ビルド時の処理を最大化する ビルド時にかかる時間はユーザーには見えないため、可能な処理はすべてイメージのビルド段階に移します。

• 依存関係の完全なインストール
• データベーススキーマのセットアップ
• アプリの初回実行とテストスイートの実行（キャッシュを構築）

自己起動エージェント

エージェントが起動するセッション 最先端のモデルは作業を分解し、サブタスクを調整できるため、エージェントが新しいセッションを起動できるツールを構築します。

• 複数のリポジトリにまたがる調査タスク
• 大規模な変更におけるサブタスクの並列実行
• 1 つの大きなタスクから、複数の小規模な PR を作成

次の 3 つのプリミティブを公開します。指定したパラメーターで新しいセッションを開始する機能、任意のセッションの状態を読み取る機能（状況確認機能）、サブセッションを並行して実行しながらメインの作業を続ける機能です。

自己起動のためのプロンプトエンジニアリング エージェントが作業をその場で進めるのではなく、サブセッションを起動すべきタイミングを指示するプロンプトを設計します。

• リポジトリ横断の調査が必要なタスク
• 一枚岩の変更を小規模な PR に分割する作業
• 異なるアプローチを並行して検討する作業

API レイヤー

セッションごとの状態分離 セッションごとに状態を分離します（セッションごとの SQLite が適しています）。セッション間の干渉は、見つけにくくデバッグも困難な障害につながるためです。

• セッションごとに専用のデータベースを用意します
• あるセッションが別のセッションのパフォーマンスに影響を与えることはありません
• 数百の同時セッションに対応するアーキテクチャにします

リアルタイムストリーミング ユーザーの信頼を得るには頻繁なフィードバックが不可欠なため、エージェントの作業をすべてリアルタイムでストリーミングします。

• モデルプロバイダーからのトークンストリーミング
• ツール実行状況の更新
• ファイル変更の通知

ハイバネーション API を備えた WebSocket 接続を使用し、接続を開いたまま維持しつつ、アイドル時のコンピューティングコストを削減します。

クライアント間の同期 チャットインターフェイス、Slack ボット、Chrome 拡張機能、ウェブインターフェイス、VS Code の各インスタンスなど、すべてのクライアント間で同期する単一の状態システムを構築します。ユーザーは頻繁に利用する画面を切り替え、作業の継続性を期待するためです。すべての変更がセッションの状態に同期されるため、クライアントをシームレスに切り替えられます。

マルチプレイヤーのサポート

マルチプレイヤーが重要な理由 適切な同期アーキテクチャがあれば、マルチプレイヤー対応の追加はほぼ無料であり、価値の高いワークフローを実現できるため、初日からマルチプレイヤーを前提に設計します。

• エンジニア以外のメンバーが AI を効果的に使えるように教える
• 複数のチームメンバーが参加するライブ QA セッション
• 変更をすぐに反映するリアルタイムの PR レビュー
• 共同でのデバッグセッション

実装要件 作成者情報がハードコードされているとマルチプレイヤー対応が気付かれないまま失敗するため、セッションが単一の作成者に紐付かないようデータモデルを構築します。

• 各プロンプトに作成者情報を渡します
• コードの変更を、プロンプトを送信したユーザーに帰属させます
• すぐに共同作業できるよう、セッションリンクを共有します

認証と認可

ユーザー名義のコミット 監査証跡を維持し、ユーザーが自分のAI生成変更を承認するのを防ぐため、アプリではなくユーザー本人に代わってPRを作成する際はGitHub認証を使用します。

• PR作成用のユーザートークンを取得します
• PRはボットではなく、人間が作成したものとして表示されます

サンドボックスからAPIへのフロー サンドボックスの権限を最小限に抑えながら、機密性の高い操作をAPIに任せられるよう、次の手順に従います。

1. サンドボックスが変更をプッシュします（gitユーザー設定を更新します）
2. サンドボックスがブランチ名とセッションIDをAPIに送信します
3. APIがユーザーのGitHubトークンを使ってPRを作成します
4. GitHubのWebhookがPRイベントをAPIに通知します

クライアントの実装

Slackとの統合 チームメンバーが他の人の利用を目にすることでバイラリティループが生まれるため、社内での導入に向けて、最初の配布チャネルとしてSlackを優先します。

• 構文を覚える必要のない、自然なチャットインターフェース
• 作業対象のリポジトリを判定する分類器（リポジトリの説明を使う高速モデル）を構築します
• よく使うリポジトリのヒントを含め、判断が難しい場合は「unknown」を選べるようにします

Webインターフェース パワーユーザー向けの主要なインターフェースとなるよう、次の機能を備えたWebインターフェースを構築します。

• デスクトップとモバイルで、エージェントの作業をリアルタイムにストリーミングします
• サンドボックス内で稼働するホスト型VS Codeインスタンス
• 視覚的な確認に使える、ストリーミング配信のデスクトップ表示
• PRの変更前・変更後のスクリーンショット
• 統計ページ：マージ済みPRにつながったセッション数（主要指標）、時間経過に伴う利用状況、「プロンプトを入力中の人間」のリアルタイム数

Chrome拡張機能 DOMやReact内部情報を抽出すれば、未加工のスクリーンショットよりも低いトークンコストで高い精度を得られるため、エンジニア以外のユーザー向けにChrome拡張機能を構築します。

• スクリーンショットツールを備えたサイドバーチャットインターフェース
• 未加工の画像ではなく、DOMやReact内部情報を抽出します
• 管理対象デバイスのポリシーを使って配布します（Chromeウェブストアを介さずに配布できます）

実践的なガイダンス

ホスト型エージェント設計のチェックリスト

システムを構築する前に、次のインフラ特性を明確に決めます。

1. サンドボックスのライフサイクル：セッションの開始、スナップショット作成、復元、タイムアウト、終了の方法。
2. イメージとウォームプールのポリシー：イメージの再構築頻度、事前計算するキャッシュ、ウォームサンドボックスの有効期限。
3. 読み取り／書き込みの同期：リポジトリの同期完了前にエージェントが読み取り可能かどうか、書き込みを許可するイベント。
4. セッションごとの状態分離：各セッションに属するストレージ、共有するストレージ、セッション間の干渉を防ぐ方法。
5. 認証とコミットの識別情報：アプリトークンを使用する操作、ユーザートークンを使用する操作、コミットの帰属先。
6. 出力の抽出：ブランチ、PR、ファイル、ログ、スクリーンショット、セッションの概要をサンドボックスの外に取り出す方法。
7. 予算と終了処理：最大実行時間、コスト上限、アイドル時のポリシー、強制クリーンアップの動作。

実行中に届くフォローアップメッセージの処理

実行中に送信されたフォローアップメッセージをキューに入れるか、挿入するかを選びます。キュー方式は管理が簡単で、エージェントの作業中にユーザーが次の手順についての考えを送れるため、こちらを推奨します。必要に応じて実行中のエージェントを停止する仕組みも構築してください。これがないと、ユーザーは身動きが取れないと感じます。

重要な指標

見せかけの利用状況ではなく、実際の価値を示す次の指標を追跡します。

• マージ済みPRにつながったセッション数（主要な成功指標）
• セッション開始から最初のモデル応答までの時間
• PRの承認率と修正回数
• リポジトリ全体におけるエージェント作成コードの割合

導入戦略

利用を強制すると反感を招くため、義務化ではなく可視性を通じて社内導入を促進します。

• Slackチャンネルなど、人目に触れる場所で作業します
• プロダクトを通じてバイラリティループを生み出します
• 既存のツールを使い続けることを妨げません
• 仮定上の要件ではなく、人々のニーズに合わせて構築します

例

例 1：バックグラウンドコーディングセッションのライフサイクル

user prompt
-> API allocates warm sandbox from current image
-> sandbox syncs latest branch delta
-> reads allowed immediately, writes blocked until sync completes
-> agent edits and tests inside isolated workspace
-> sandbox snapshots final filesystem
-> branch is pushed
-> API creates PR using user token
-> session summary, logs, and PR URL are returned to clients

このシーケンスでは、監査可能性とコード変更に対するユーザーの所有権を維持しながら、セットアップ作業をユーザーに見える処理経路の外で行います。

例 2：境界の判断

タスクが「ロックされた評価基準と PR 承認を備え、エージェントループを何日も稼働させる」ことであれば、harness-engineering を使用してください。タスクが「ウォームプール、セッションスナップショット、ストリーミングクライアント、ユーザーが作成する PR を備えたリモートサンドボックスで、そのループを実行する」ことであれば、このスキルを使用してください。

ガイドライン

1. 環境イメージを定期的に事前ビルドします（デフォルトでは 30 分が適切です）
2. ユーザーが送信するのを待たず、入力を始めた時点でサンドボックスのウォームアップを開始します
3. Git の同期が完了する前でもファイルの読み取りを許可し、書き込みのみをブロックします
4. エージェントフレームワークはサーバー優先で構成し、クライアントは薄いラッパーにします
5. セッション間の干渉を防ぐため、状態をセッションごとに分離します
6. コミットの作成者はアプリではなく、プロンプトを入力したユーザーとして記録します
7. マージされた PR を主要な成功指標として追跡します
8. 適切な同期アーキテクチャを使えばほぼ追加コストなしで実現できるため、最初からマルチプレイヤー対応にします

注意点

1. コールドスタートの遅延：最初のサンドボックス起動には 30～60 秒かかり、ユーザーには壊れているように感じられます。ウォームプールとキー入力に応じた予測的なウォームアップを使い、待ち時間を感じさせないようにします。
2. イメージの陳腐化：イメージの再ビルド頻度が低いと、エージェントが古い依存関係やコードを使って実行されます。30 分ごとの再ビルドを設定してイメージの経過時間を監視し、ビルドが失敗しても通知されない場合はアラートを出します。
3. サンドボックスのコスト超過：タイムアウトや予算上限のない長時間稼働のエージェントは、予想外のコストを積み上げます。厳格なタイムアウト上限（デフォルトは 4 時間）とセッションごとのコスト上限を設定します。
4. セッション中の認証トークンの期限切れ：GitHub トークンが途中で期限切れになると、長時間のタスクは失敗します。トークンを更新するロジックを実装し、PR の作成などの機密性の高い操作の前にトークンの有効性を確認します。
5. サンドボックス内の Git 設定：user.name または user.email が設定されていないと、バックグラウンドエージェントのコミットが失敗します。イメージから設定が引き継がれると想定せず、サンドボックスの構成時に必ず Git のユーザー情報を明示的に設定します。
6. サンドボックスの再利用時の状態消失：結果を取り出す前にサンドボックスが再利用されたりタイムアウトしたりすると、エージェントが完了した作業が失われます。終了前に必ずスナップショットを作成し、サンドボックスを終了させる前に成果物（ブランチ、PR、ファイル）を取り出します。
7. ウォームプールの過剰な確保：ウォーム状態のサンドボックスを多く維持しすぎると、トラフィックが少ない時間帯に無駄なコストが発生します。トラフィックパターンや時間帯に応じてプールのサイズを調整し、固定サイズのプールではなくオートスケーリングを使用します。
8. 出力の取り出し漏れ：エージェントがサンドボックス内で作業を完了しても、結果がユーザーに返されないことがあります。セッションの終了処理に、明示的な取り出し手順（ブランチのプッシュ、PR の作成、ファイル内容の返却）を組み込みます。

統合

このスキルはホスト型ランタイムのインフラストラクチャを担当します。隣接するスキルは、制御システム、トポロジー、ツールの契約を担当します。

• harness-engineering：自律的な作業におけるガバナンス、ロックされた評価器、ロールバック、新規性ゲート、人間による承認の境界。
• multi-agent-patterns：ホスト型インフラストラクチャが整った後の自己生成パターンとスーパーバイザーパターン。
• tool-design：エージェントに公開する起動、状態確認、終了、PR の各ツール。
• context-optimization：分散型ホストセッション全体にわたるコンテキストの管理。
• filesystem-context：永続的なセッション状態や成果物にサンドボックスのファイルシステムを使用する方法。

参考資料

内部資料：

• インフラストラクチャのパターン - 初めてサンドボックスのライフサイクル、イメージのビルド、またはウォームプールのロジックを実装するときに参照してください

このコレクション内の関連スキル：

• multi-agent-patterns - 自己生成型パターンまたはスーパーバイザーとの連携パターンを設計するときに参照してください
• tool-design - エージェントのセッション管理やステータス確認用のツールを構築するときに参照してください
• context-optimization - 分散エージェントセッション間でコンテキストウィンドウがいっぱいになるときに参照してください

外部リソース：

• Ramp - バックグラウンドエージェントのインフラストラクチャを自社で構築するか、購入するかを評価するときに参照してください
• Modal Sandboxes - クラウドサンドボックスプロバイダーを選ぶとき、または分離モデルを比較するときに参照してください
• Cloudflare Durable Objects - WebSocket のハイバネーションを利用したセッションごとの状態管理を設計するときに参照してください
• OpenCode - サーバーファーストのエージェントフレームワークを選ぶとき、またはプラグインアーキテクチャを調査するときに参照してください

---

スキルのメタデータ

作成日：2026-01-12 最終更新日：2026-05-15 作成者：Agent Skills for Context Engineering Contributors バージョン：1.2.0