クラウド セッション

Prerequisites

クラウド セッションを作成する前に、次のことを確認してください。

• ユーザーは、クラウド エージェントの権利を持つCopilotアクセス権を持っています。
• セッションは、ユーザー トークンまたはログイン Copilot CLI ID を使用して、GitHubに対して認証できます。
• セッションを GitHub リポジトリに関連付けることができます。 これは SDK の種類では省略可能ですが、クラウド エージェントに正しいリポジトリ コンテキストが含まれるようにすることをお勧めします。
• 組織ポリシーを使用すると、クラウド サーフェスからのリモート 制御とセッションの表示が可能になります。

クラウド セッションの作成

create-session cloud オプションを設定して、クラウド セッションを作成します。 リポジトリ メタデータを含め、クラウド セッションを GitHub リポジトリに関連付けることができます。

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

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

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

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

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

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 はエージェントがタスクを予約するとすぐに解決されますが、リモート copilot-agent ワーカーは接続して session.startを出力するためにもう 1 秒または 2 秒かかります。 その前にsession.sendを呼び出すと、ランタイムのRemoteSession.sendは"Remote session is still starting"をスローしますが、スキーマ ラッパーは起動して忘れ、コードに新しいmessageIdを返しながらエラーを自動的に飲み込みます。 プロンプトはサーバー上で削除され、ワーカーに到達することはありません。

確実に送信するには、送信前にイベントを購読し、session.start が producer である最初の "copilot-agent" イベントを待ちます:

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<void>((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 をレンダリングしている場合、チャットはフリーズした状態で表示されます。 「ストリーミング セッション イベント」を参照してください。
• このレースに影響を受けるのは、最初session.sendのものだけです。 ランタイムはセッションの有効期間中に hasSessionStarted 設定を維持するため、同じセッションでの後続の送信は正常に動作します。
• ready promise の周りにタイムアウト (60 秒など) を適用して、スタックしたセッションがアプリを永久にハングしないようにします。
• すべての SDK 言語で同じパターンが機能します。 session.startをサブスクライブし、 producer === "copilot-agent"確認してから、 sendを呼び出します。

エージェント セッション URL へのアクセス

クラウド セッションは本質的にリモートです。ワーカーが接続すると、セッションは https://github.com/copilot/tasks/{sessionId} に発行され、ランタイムは URL を含む session.info イベントを生成します。 remote.enable()を呼び出す必要はありません。この API は、ローカル セッションを GitHub に同期するためだけに使用されます。

session.infoをサブスクライブして URL をキャプチャし、infoType: "remote"でフィルター処理します。

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 を介して昇格されたローカル セッションで同一の配線構成を使用する場合は、リモート セッション を参照してください。

リポジトリの関連付け

cloud.repository オブジェクトは、クラウド セッションを GitHub リポジトリに関連付けます。

フィールド	必須	Description
owner	はい	リポジトリの所有者または組織。
name	はい	リポジトリ名。
branch	いいえ	リポジトリ コンテキストに使用するブランチ。 ランタイムが既定のブランチまたは現在のリポジトリ コンテキストを選択できるようにするには、これを省略します。

SDK の種類ではリポジトリの関連付けは省略可能ですが、アプリがターゲット リポジトリを認識するたびにそれを含めます。 エージェント パネルに適切なリポジトリ コンテキストでセッションが表示され、クラウド エージェントの開始点が明確になります。

特定のブランチから作業を開始する必要がある場合は、 branch を使用します。 アプリがプル要求、トリアージ フロー、またはデプロイ ワークフローからセッションを作成している場合は、ユーザーが表示するタスクに一致するブランチを渡します。

クラウド セッションの再開

cloud オプションは、新しいセッションを作成する場合にのみ適用されます。 既存のクラウド セッションを再開するには、SDK 言語の標準の再開 API を使用します。

const session = await client.resumeSession("session-id", {
  onPermissionRequest: async () => ({ kind: "approve-once" }),
});

再開時に cloud を再度渡さないでください。 保存されたセッション メタデータは、セッションがクラウドでサポートされていることを判断し、再開は通常のセッション再開パスに従います。

組織のポリシーと権利

クラウド セッションの作成は、ユーザーまたは組織がクラウド エージェントの実行を受ける権利がない場合、または組織レベルのポリシーによってフローがブロックされた場合に失敗する可能性があります。 特に、クラウド サンドボックスのポリシーにより、クライアントがクラウド タスクを作成できなくなる可能性があります。

これが発生すると、ランタイムはクラウド タスクの作成 "policy_blocked" エラーの理由を報告します。 これは、一時的なインフラストラクチャ障害ではなく、承認またはポリシーの結果として扱います。

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 は、ルーティング、属性、および統合固有の動作に使用されます。

マルチユーザー サーバーのガイダンスと完全な統合 ID の詳細については、 AUTOTITLE を参照してください。

SDK で作成されたクラウド セッションは、 copilot-developer-sandbox エージェント のスラッグにルーティングされます。 この名前はクラウド エージェントの内部ルーティング スラッグであり、セッションがローカル Windows サンドボックスを使用するわけではありません。

詳細: COPILOT_MC_BASE_URL

既定では、ランタイムは、構成された Copilot API URL からエージェント セッションのベース URL を派生させます。 COPILOT_MC_BASE_URLは、そのセッション エンドポイントをオーバーライドする必要がある場合にのみ設定します。

これは、GitHub Enterprise Server の展開に必要な場合があります。 運用環境で使用する前に、GitHub担当者に正しい値とサポートの状態を確認してください。

COPILOT_MC_BASE_URL="https://example.com/agents"

クラウド セッションとリモート セッション

能力	リモート セッション	クラウド セッション
実行場所	ローカル マシンまたはお使いのサーバー	GitHubホスト型コンピューティング
セッションの役割	ローカル セッションを GitHub の Web/モバイル版と共有する	ホストされているセッションを作成してルーティングする
SDK オプション
remote: true クライアントまたはセッション上で
cloud: { ... } セッションの作成時
再開パス	標準履歴書	標準履歴書
Windows サンドボックス関連	無関係	無関係

SDK ランタイムが既に実行されている場所でセッションを実行する必要があるが、 GitHubのエージェント パネルからもアクセスできる場合は、リモート セッションを使用します。 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" イベントを待機します。 最初のプロンプトの送信を参照してください
クラウド ワーカーが処理している場合でも、ライブ UI が更新されることはありません
streaming が createSessionに設定されていないため、最終的な assistant.message のみが出力されます
streaming: trueにcreateSessionを設定して再起動する
クラウド セッションは機能しますが、UI に共有可能な URL は表示されません	アプリが URL の session.info をサブスクライブしたことがない
session.infoをサブスクライブし、infoType === "remote"をフィルター処理します。
エージェント セッション URL へのアクセスを参照してください

参照

• リモート セッション: ローカルでホストされているセッションをエージェント パネルで共有する GitHub
• ストリーミング セッション イベント: ライブUIレンダリングのためにassistant.*デルタを購読する
• マルチテナントとサーバーの展開: 統合 ID とサーバーデプロイ パターン
• 認証: SDK セッションのGitHub認証を構成する