Copilot SDK でバンドルされた CLI を使用する

メモ

          Copilot SDK は現在 テクニカル プレビューです。 機能と可用性は変更される場合があります。

          Copilot CLI (コパイロット CLI)をアプリケーションの一部として配布し、ユーザーが追加のセットアップを開始できないようにします。

          **次の場合に最適です。** デスクトップ アプリ、スタンドアロン ツール、Electron アプリ、および再頒布可能 CLI ユーティリティ。

どのように機能するのか

グローバルにインストールされた CLI に依存する代わりに、アプリケーションバンドルに CLI バイナリを含めます。 SDK は、 cliPath オプションを使用してバンドルされたコピーを指します。主な特性は次のとおりです。

CLI バイナリはアプリに付属しています。個別のインストールは必要ありません。
アプリで使用する CLI の正確なバージョンを制御します。
ユーザーは、アプリ、環境変数、または BYOK を使用して認証します。
セッションは、コンピューター上のユーザーごとに管理されます。

セットアップ

手順 1: CLI をプロジェクトに含める

CLI は、 @github/copilot npm パッケージの一部として配布されます。

npm install @github/copilot

手順 2: SDK をバンドル済みの CLI に設定する

Node.js/ TypeScript

import { CopilotClient } from "@github/copilot-sdk";
import path from "path";

const client = new CopilotClient({
    // Point to the CLI binary in your app bundle
    cliPath: path.join(__dirname, "vendor", "copilot"),
});

const session = await client.createSession({ model: "gpt-4.1" });
const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();

Python

from copilot import CopilotClient, PermissionHandler
from pathlib import Path

client = CopilotClient({
    "cli_path": str(Path(__file__).parent / "vendor" / "copilot"),
})
await client.start()

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-4.1")
response = await session.send_and_wait({"prompt": "Hello!"})
print(response.data.content)

await client.stop()

Go

client := copilot.NewClient(&copilot.ClientOptions{
    CLIPath: "./vendor/copilot",
})
if err := client.Start(ctx); err != nil {
    log.Fatal(err)
}
defer client.Stop()

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
fmt.Println(*response.Data.Content)

.NET

var client = new CopilotClient(new CopilotClientOptions
{
    CliPath = Path.Combine(AppContext.BaseDirectory, "vendor", "copilot"),
});

await using var session = await client.CreateSessionAsync(
    new SessionConfig { Model = "gpt-4.1" });

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello!" });
Console.WriteLine(response?.Data.Content);

認証の戦略

CLI をバンドルするときは、ユーザーの認証方法を決定する必要があります。次の図は、一般的なパターンを示しています。

バンドルされた CLI デプロイの認証戦略オプションを示す図。

オプション A: ユーザーのサインイン資格情報 (最も単純)

ユーザーは CLI に 1 回サインインし、バンドルされたアプリはこれらの資格情報を使用します。追加のコードは必要ありません。これが既定の動作です。

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
    // Default: uses signed-in user credentials
});

オプション B: 環境変数を使用したトークン

プログラムでトークンを設定するか、アプリを開始する前にトークンを設定するようにユーザーに指示します。

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
    env: {
        COPILOT_GITHUB_TOKEN: getUserToken(),
    },
});

          `getUserToken()`を、ユーザーの GitHub OAuth トークンを取得するアプリ内のロジックに置き換えます。

オプション C: BYOK ( GitHub 認証は必要ありません)

独自のモデルプロバイダーキーを管理する場合、ユーザーは GitHub アカウントを必要としません。

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
});

const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "openai",
        baseUrl: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY,
    },
});

セッション管理

バンドルされたアプリでは、通常、ユーザーが会話を再開できるように、名前付きセッションが必要です。

const client = new CopilotClient({
    cliPath: path.join(__dirname, "vendor", "copilot"),
});

// Create a session tied to the user's project
const sessionId = `project-${projectName}`;
const session = await client.createSession({
    sessionId,
    model: "gpt-4.1",
});

// Resume the session in a later run
const resumed = await client.resumeSession(sessionId);

セッションの状態は ~/.copilot/session-state/SESSION-ID/に格納されます。ここで、 SESSION-ID は指定したセッション ID です。

分散パターン

デスクトップアプリ (Electron、Tauri)

アプリの resources ディレクトリに CLI バイナリを含めます。

import { app } from "electron";
import path from "path";

const cliPath = path.join(
    app.isPackaged ? process.resourcesPath : __dirname,
    "copilot"
);

const client = new CopilotClient({ cliPath });

CLI ツール

再頒布可能 CLI ツールの場合は、バイナリに対する相対パスを解決します。

import { fileURLToPath } from "url";
import path from "path";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const cliPath = path.join(__dirname, "..", "vendor", "copilot");

const client = new CopilotClient({ cliPath });

プラットフォーム固有のバイナリ

複数のプラットフォームに配布する場合は、ターゲットごとに適切なバイナリを含めます。

my-app/
├── vendor/
│   ├── copilot-darwin-arm64    # macOS Apple Silicon
│   ├── copilot-darwin-x64      # macOS Intel
│   ├── copilot-linux-x64       # Linux x64
│   └── copilot-win-x64.exe     # Windows x64
└── src/
    └── index.ts

import os from "os";

function getCLIPath(): string {
    const platform = process.platform;   // "darwin", "linux", "win32"
    const arch = os.arch();              // "arm64", "x64"
    const ext = platform === "win32" ? ".exe" : "";
    const name = `copilot-${platform}-${arch}${ext}`;
    return path.join(__dirname, "vendor", name);
}

const client = new CopilotClient({
    cliPath: getCLIPath(),
});

制限事項

制限事項	詳細情報
バンドルサイズ	CLI バイナリは、アプリの配布サイズに追加されます。
Updates	CLI バージョンの更新は、リリースサイクルで管理します。
プラットフォームビルド	OS/アーキテクチャごとに個別のバイナリが必要です。
単一ユーザー	バンドルされた各 CLI インスタンスは、1 人のユーザーにサービスを提供します。

次のステップ

GitHub アカウントを使用してサインインするユーザーについては、「Copilot SDK での GitHub OAuth の使用」を参照してください。
ユーザーマシンではなくサーバーで実行する方法については、「バックエンドサービス用の Copilot SDK の設定」を参照してください。
インストールと最初のメッセージについては、 Copilot SDK のはじめにを参照してください。