# クラウド セッション クラウド セッションでは、Mission Control を通じて、GitHub がホストするコンピューティング環境で Copilot の作業を実行します。 ユーザーのコンピューターまたはサーバーでローカル Copilot CLI セッションを開始するのではなく、リモートで実行するセッションをアプリで作成する必要がある場合に使用します。 ## Prerequisites クラウド セッションを作成する前に、次のことを確認してください。 * ユーザーは、クラウド エージェントの権利を持つCopilotアクセス権を持っています。 * セッションは、ユーザー トークンまたはログイン Copilot CLI ID を使用して、GitHubに対して認証できます。 * セッションを GitHub リポジトリに関連付けることができます。 これは SDK の種類では省略可能ですが、Mission Control とクラウド エージェントにリポジトリ コンテキストが含まれるようにすることをお勧めします。 * 組織ポリシーを使用すると、クラウド サーフェスからのリモート 制御とセッションの表示が可能になります。 ## クラウド セッションの作成 create-session `cloud` オプションを設定して、クラウド セッションを作成します。 リポジトリ メタデータを含め、クラウド セッションを GitHub リポジトリに関連付けることができます。 ### TypeScript ```typescript import { CopilotClient } from "@github/copilot-sdk"; const client = new CopilotClient(); await client.start(); const session = await client.createSession({ onPermissionRequest: async () => ({ kind: "approve-once" }), cloud: { repository: { owner: "github", name: "copilot-sdk", branch: "main", }, }, }); ``` ### Python ```python from copilot import ( CloudSessionOptions, CloudSessionRepository, CopilotClient, PermissionHandler, ) client = CopilotClient() await client.start() session = await client.create_session( on_permission_request=PermissionHandler.approve_all, cloud=CloudSessionOptions( repository=CloudSessionRepository( owner="github", name="copilot-sdk", branch="main", ) ), ) ``` ### Go ```golang client := copilot.NewClient(nil) if err := client.Start(ctx); err != nil { return err } session, err := client.CreateSession(ctx, &copilot.SessionConfig{ Cloud: &copilot.CloudSessionOptions{ Repository: &copilot.CloudSessionRepository{ Owner: "github", Name: "copilot-sdk", Branch: "main", }, }, OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) { return &rpc.PermissionDecisionApproveOnce{}, nil }, }) _ = session ``` ### .NET ```csharp await using var client = new CopilotClient(); var session = await client.CreateSessionAsync(new SessionConfig { Cloud = new CloudSessionOptions { Repository = new CloudSessionRepository { Owner = "github", Name = "copilot-sdk", Branch = "main", }, }, OnPermissionRequest = (req, inv) => Task.FromResult(PermissionDecision.ApproveOnce()), }); ``` ### Java ```java import com.github.copilot.CopilotClient; import com.github.copilot.rpc.*; try (var client = new CopilotClient()) { client.start().get(); var session = client.createSession( new SessionConfig() .setCloud(new CloudSessionOptions() .setRepository(new CloudSessionRepository() .setOwner("github") .setName("copilot-sdk") .setBranch("main"))) .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) ).get(); } ``` ### Rust ```rust use std::sync::Arc; use github_copilot_sdk::{CloudSessionOptions, CloudSessionRepository, SessionConfig}; use github_copilot_sdk::handler::ApproveAllHandler; let session = client.create_session( SessionConfig::default() .with_cloud(CloudSessionOptions::with_repository( CloudSessionRepository::new("github", "copilot-sdk").with_branch("main"), )) .with_permission_handler(Arc::new(ApproveAllHandler)), ).await?; ``` ## 最初のプロンプトの送信 クラウド セッションは 2 つのフェーズで初期化されます。 `createSession` は、Mission Control がタスクを予約するとすぐに解決されますが、リモート `copilot-agent` ワーカーは接続して `session.start`を出力するためにもう 1 秒または 2 秒かかります。 その前に `session.send` を呼び出すと、ランタイムの `RemoteSession.send` が `"Remote session is still starting"` をスローします。しかし、スキーマ ラッパーは「ファイア アンド フォーゲット」方式であり、**エラーをサイレントに吸収し**つつ、コードには新しい `messageId` を返します。 プロンプトはサーバー上で削除され、ワーカーに到達することはありません。 確実に送信するには、送信**前**にイベントを購読し、`session.start` が `producer` である最初の `"copilot-agent"` イベントを待ちます: ```typescript import { CopilotClient, type CopilotSession } from "@github/copilot-sdk"; const client = new CopilotClient(); await client.start(); const session: CopilotSession = await client.createSession({ streaming: true, // required for assistant.message_delta to fire cloud: { repository: { owner: "github", name: "copilot-sdk" } }, onPermissionRequest: async () => ({ kind: "approve-once" }), }); // Subscribe BEFORE sending so you don't miss the start event. const ready = new Promise((resolve) => { const off = session.on("session.start", (event) => { if (event.data?.producer === "copilot-agent") { off(); resolve(); } }); }); await ready; await session.send({ prompt: "Summarize the README" }); ``` いくつかの注意事項: * ランタイムが`streaming: true`イベントを出力するように、`createSession`に`assistant.message_delta`を設定します。 これを使用しない場合、最終的な `assistant.message` が得られる唯一のアシスタント シグナルです。バッチ使用には問題ありませんが、ライブ UI をレンダリングしている場合、チャットはフリーズした状態で表示されます。 「[ストリーミング セッション イベント](/ja/copilot/how-tos/copilot-sdk/features/streaming-events)」を参照してください。 * このレースに影響を受けるのは、**最初**`session.send`のものだけです。 ランタイムはセッションの有効期間中に `hasSessionStarted` 設定を維持するため、同じセッションでの後続の送信は正常に動作します。 * `ready` プロミスに対してタイムアウト (例: 60 秒) を設定し、Mission Control のプロビジョニングがスタックしてもアプリが永久にハングアップしないようにします。 * すべての SDK 言語で同じパターンが機能します。 `session.start`をサブスクライブし、 `producer === "copilot-agent"`確認してから、 `send`を呼び出します。 ## ミッション コントロール URL へのアクセス クラウド セッションは本質的にリモートです。ワーカーが接続すると、Mission Control は `https://github.com/copilot/tasks/{sessionId}` でセッションを発行し、ランタイムは URL を使用して `session.info` イベントを生成します。 \*\* \*\*を呼び出す必要`remote.enable()`。その API は、ローカル セッションを Mission Control に昇格させるためだけに使用されます。 `session.info`をサブスクライブして URL をキャプチャし、`infoType: "remote"`でフィルター処理します。 ```typescript session.on("session.info", (event) => { if (event.data?.infoType === "remote" && event.data.url) { console.log("Open from web or mobile:", event.data.url); // For example, surface in your UI as a shareable link or QR code. } }); ``` イベントは、`session.start` の直後に発生します。 イベントが既に発生した後にレンダラーがマウントされる場合は、URL をアプリの状態でセッション レコードと共に保持し、再マウント時にリハイドレートします。ランタイムは、それ自体で `session.info` を再出力しません。 `remote: true` を介して昇格されたローカル セッションで同一の配線構成を使用する場合は、[リモート セッション](/ja/copilot/how-tos/copilot-sdk/features/remote-sessions) を参照してください。 ## リポジトリの関連付け `cloud.repository` オブジェクトは、クラウド セッションを GitHub リポジトリに関連付けます。 | フィールド | 必須 | Description | | -------- | --- | ----------------------------------------------------------------------------- | | `owner` | はい | リポジトリの所有者または組織。 | | `name` | はい | リポジトリ名。 | | `branch` | いいえ | リポジトリ コンテキストに使用するブランチ。 ランタイムが既定のブランチまたは現在のリポジトリ コンテキストを選択できるようにするには、これを省略します。 | SDK の種類ではリポジトリの関連付けは省略可能ですが、アプリがターゲット リポジトリを認識するたびにそれを含めます。 これは、Mission Control がセッションを適切なコンテキストで表示するのに役立ち、クラウド エージェントに明確な開始点を提供します。 特定のブランチから作業を開始する必要がある場合は、 `branch` を使用します。 アプリがプル要求、トリアージ フロー、またはデプロイ ワークフローからセッションを作成している場合は、ユーザーが表示するタスクに一致するブランチを渡します。 ## クラウド セッションの再開 `cloud` オプションは、新しいセッションを作成する場合にのみ適用されます。 既存のクラウド セッションを再開するには、SDK 言語の標準の再開 API を使用します。 ```typescript const session = await client.resumeSession("session-id", { onPermissionRequest: async () => ({ kind: "approve-once" }), }); ``` 再開時に `cloud` を再度渡さないでください。 保存されたセッション メタデータは、セッションがクラウドでサポートされていることを判断し、再開は通常のセッション再開パスに従います。 ## 組織のポリシーと権利 クラウド セッションの作成は、ユーザーまたは組織がクラウド エージェントの実行を受ける権利がない場合、または組織レベルのポリシーによってフローがブロックされた場合に失敗する可能性があります。 特に、クラウド サンドボックスのポリシーにより、クライアントがクラウド タスクを作成できなくなる可能性があります。 これが発生すると、ランタイムはクラウド タスクの作成 `"policy_blocked"` エラーの理由を報告します。 これは、一時的なインフラストラクチャ障害ではなく、承認またはポリシーの結果として扱います。 TypeScript で、再試行する前に理由を確認します。 ```typescript try { await client.createSession({ cloud: { repository } }); } catch (error) { if ((error as { reason?: string }).reason === "policy_blocked") { // Show an admin-facing message or link to org policy settings. } throw error; } ``` SDK エラーの表現が異なる言語では、表示されたエラーの理由またはコードを調べて、 `"policy_blocked"` を明示的に処理します。 ポリシーを変更せずに再試行することは成功しません。 ## 統合 ID とルーティング クラウド セッションには、`Copilot-Integration-Id` 環境変数から派生した `GITHUB_COPILOT_INTEGRATION_ID` ヘッダーがスタンプされます。 この統合 ID は、ルーティング、属性、統合固有の動作のために Mission Control によって使用されます。 マルチユーザー サーバーのガイダンスと完全な統合 ID の詳細については、 [AUTOTITLE を](/ja/copilot/how-tos/copilot-sdk/setup/multi-tenancy)参照してください。 Mission Control は、SDK で作成されたクラウド セッションを `copilot-developer-sandbox` エージェント のスラッグにルーティングします。 この名前はクラウド エージェントの内部ルーティング スラッグであり、セッションがローカル Windows サンドボックスを使用するわけではありません。 ## 詳細: `COPILOT_MC_BASE_URL` 既定では、ランタイムは、構成された Copilot API URL から Mission Control のベース URL を派生させます。 `COPILOT_MC_BASE_URL`そのミッション コントロール エンドポイントをオーバーライドする必要がある場合にのみ設定します。 これは、GitHub Enterprise Server の展開に必要な場合があります。 運用環境で使用する前に、GitHub担当者に正しい値とサポートの状態を確認してください。 ```shell COPILOT_MC_BASE_URL="https://example.com/agents" ``` ## クラウド セッションとリモート セッション | 能力 | リモート セッション | クラウド セッション | | ------------------------------- | ----------------------------------- | -------------------------- | | 実行場所 | ローカル マシンまたはお使いのサーバー | GitHubホスト型コンピューティング | | ミッション コントロールの役割 | ローカル セッションを GitHub の Web/モバイル版と共有する | ホストされているセッションを作成してルーティングする | | SDK オプション | | | | `remote: true` クライアントまたはセッション上で | | | | `cloud: { ... }` セッションの作成時 | | | | 再開パス | 標準履歴書 | 標準履歴書 | | Windows サンドボックス関連 | 無関係 | 無関係 | セッションが SDK ランタイムが既に実行されている場所で実行する必要があるが、Mission Control からもアクセスできる場合は、リモート セッションを使用します。 GitHubホストされたコンピューティングでセッションを実行する必要がある場合は、クラウド セッションを使用します。 ## Troubleshooting | 症状: | 考えられる原因 | 確認すべきこと | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- | | クラウド セッションの作成は `"policy_blocked"` を返します | 組織のポリシーにより、クラウド フローからのリモート コントロールまたはビューがブロックされる | 組織のCopilotポリシーとユーザー権利を確認する | | リポジトリ コンテキストなしでセッションが作成される | | | | `cloud.repository` が省略されました | | | | `owner`、`name`、および必要に応じて`branch`を渡します | | | | 再開で新しい `cloud` オプションが無視される | | | | `cloud` 新しいセッションにのみ適用されます | 既存のセッションを通常どおりに再開する | | | サンドボックス設定との混同 | Windowsサンドボックスセッションとクラウドセッションは別々です | クラウドの実行に `SANDBOX=true` を使用しない | | `session.send` は `messageId` で解決されますが、 `assistant.*` イベントは発生せず、ミッション コントロールはプロンプトを表示しません | session.send はリモートワーカーからの `session.start` より先に進み、ランタイムがプロンプトを飲み込んだ | 送信する前に、`session.start`で最初の`producer === "copilot-agent"` イベントを待機します。 | | [最初のプロンプトの送信を](#sending-the-first-prompt)参照してください | | | | クラウド ワーカーが処理している場合でも、ライブ UI が更新されることはありません | | | | `streaming` が `createSession`に設定されていないため、最終的な `assistant.message` のみが出力されます | | | | `streaming: true`に`createSession`を設定して再起動する | | | | クラウド セッションは機能しますが、UI に共有可能な URL は表示されません | アプリが URL の `session.info` をサブスクライブしたことがない | | | `session.info`をサブスクライブし、`infoType === "remote"`をフィルター処理します。 | | | | [ミッション コントロール URL へのアクセスを](#accessing-the-mission-control-url)参照してください | | | ## 参照 * [リモート セッション](/ja/copilot/how-tos/copilot-sdk/features/remote-sessions): Mission Control を使用してローカルでホストされるセッションを共有する * [ストリーミング セッション イベント](/ja/copilot/how-tos/copilot-sdk/features/streaming-events): ライブUIレンダリングのために`assistant.*`デルタを購読する * [マルチテナントとサーバーの展開](/ja/copilot/how-tos/copilot-sdk/setup/multi-tenancy): 統合 ID とサーバーデプロイ パターン * [認証](/ja/copilot/how-tos/copilot-sdk/auth): SDK セッションのGitHub認証を構成する