Copilot SDK와 함께 번들된 CLI 사용

참고

          코필로트 SDK가 현재 기술 미리 보기에 있습니다. 기능 및 가용성은 변경될 수 있습니다.

사용자가 추가 설정 없이 시작할 수 있도록 애플리케이션의 일부로 배송 코파일럿 CLI 합니다.

          **최적 대상:** 데스크톱 앱, 독립 실행형 도구, Electron 앱 및 배포 가능한 CLI 유틸리티.

작동 방식

전역적으로 설치된 CLI를 사용하는 대신 애플리케이션 번들에 CLI 이진 파일을 포함합니다. SDK는 cliPath 옵션을 통해 번들로 묶인 복사본을 가리킵니다. 주요 특징은 다음과 같습니다.

CLI 이진 파일은 앱과 함께 제공되는 데 별도의 설치가 필요하지 않습니다.
앱에서 사용하는 정확한 CLI 버전을 제어합니다.
사용자는 앱, 환경 변수 또는 BYOK를 통해 인증합니다.
세션은 컴퓨터에서 사용자별로 관리됩니다.

설치

1단계: 프로젝트에 CLI 포함

CLI는 npm 패키지의 @github/copilot 일부로 배포됩니다.

npm install @github/copilot

2단계: 번들된 CLI에 SDK 가리키기

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();

파이썬

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()

이동

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에 한 번 로그인하면 번들 앱에서 해당 자격 증명을 사용합니다. 추가 코드가 필요하지 않습니다. 기본 동작입니다.

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()`을(를) 사용자의 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);

세션 상태는 사용자가 제공한 세션 ID가 있는 위치에 ~/.copilot/session-state/SESSION-ID/ 저장SESSION-ID됩니다.

배포 패턴

데스크톱 앱(Electron, Tauri)

앱의 리소스 디렉터리에 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(),
});

제한점

Limitation	세부 정보

          **번들 크기** | CLI 이진 파일은 앱의 배포 크기에 추가됩니다. |

다음 단계

계정으로 GitHub 로그인하는 사용자의 경우 Copilot SDK와 함께 GitHub OAuth 사용을 참조하세요.
사용자 컴퓨터 대신 서버에서 실행하려면 백 엔드 서비스에 대한 Copilot SDK 설정을 참조하세요.
설치 및 첫 번째 메시지는 Copilot SDK 사용 시작하기을 참조하세요.

누가 이 기능을 사용할 수 있나요?

이 기사에서