GitHub Copilot SDK란?

  • 8분

GitHub Copilot SDK는 자체 애플리케이션에 AI 에이전트 런타임을 포함할 수 있는 다중 플랫폼 도구 키트(현재 Technical Preview)입니다. SDK는 GitHub Copilot CLI 뒤에 있는 동일한 엔진을 프로그래밍 가능한 인터페이스로 노출하여 앱이 자연어 지침을 이해하고, 작업을 계획하고, 도구를 호출하여 이러한 지침을 충족할 수 있도록 합니다. 모든 인프라를 처음부터 빌드할 필요는 없습니다.

AI 에이전트에 SDK를 사용하는 이유는 무엇인가요?

처음부터 완전한 기능을 갖춘 AI 에이전트를 구축하는 것은 복잡합니다. 여러 번 대화 상태 관리를 처리하고, 어떤 외부 API를 호출할지 결정하고, AI의 응답이 경계 내에 유지되도록 하고, 여러 작업에 대한 여러 AI 모델을 관리하고, 안전 조치를 구현해야 합니다. 에이전트 워크플로를 처음부터 빌드한다는 것은 비즈니스 논리에 도착하기 전에 기본적으로 미니 플랫폼을 빌드했음을 의미합니다.

GitHub Copilot SDK는 미리 빌드된 프로덕션 테스트 에이전트 엔진을 제공하여 이러한 복잡성을 제거합니다. SDK는 인증, 모델 관리, 채팅 세션 및 스트리밍을 처리합니다. 이러한 구성 요소( 도메인별 도구 및 비즈니스 논리)를 기반으로 빌드되는 항목에 집중합니다.

아키텍처 개요

GitHub Copilot SDK는 로컬 프로세스로 서버 모드에서 실행되는 GitHub Copilot CLI와 통신합니다. SDK는 CLI 프로세스 수명 주기를 자동으로 관리합니다. 모든 SDK 언어는 이 동일한 아키텍처를 공유합니다.

아키텍처는 다음 흐름을 따릅니다.

Your Application → SDK Client → (JSON-RPC) → Copilot CLI (server mode)

선택한 프로그래밍 언어로 클라이언트 라이브러리를 통해 SDK와 상호 작용합니다. SDK는 통신 프로토콜을 처리하므로 원시 메시지 대신 간단한 메서드 호출을 사용합니다.

언어 지원

SDK는 다음과 같은 네 가지 프로그래밍 언어에 대한 idiomatic 라이브러리를 제공합니다.

언어 Package
Node.js(TypeScript) npm install @github/copilot-sdk
파이썬 pip install github-copilot-sdk
Go go get github.com/github/copilot-sdk/go
.NET(C#) dotnet add package GitHub.Copilot.SDK

TypeScript에서 웹 애플리케이션을 빌드하든 C#의 백 엔드 서비스를 빌드하든 동일한 AI 에이전트 기능을 통합할 수 있습니다.

주요 기능

SDK는 AI 에이전트 빌드를 간소화하는 몇 가지 기본 제공 기능을 제공합니다.

생산 등급 에이전트 반복

SDK는 GitHub Copilot CLI를 구동하는 동일한 검증된 실행 루프를 제공합니다. 이 실행 루프는 다중 턴 대화를 관리하고, 도구를 호출하고, 작업이 완료될 때까지 반복합니다. 계획 및 오케스트레이션 논리를 코딩할 필요가 없습니다.

도구 조정 및 통합

추론 프로세스 중에 AI 에이전트가 필요에 따라 호출하는 사용자 지정 도구를 정의할 수 있습니다. 도구를 등록할 때(예: lookupCustomer(id)) 에이전트의 AI 모델은 도구를 호출할 시기를 결정할 수 있습니다. SDK는 AI가 코드를 추측하는 대신 런타임의 실제 함수 호출을 통해 구조화된 방식으로 도구를 호출할 수 있도록 배선을 처리합니다.

.NET에서는 Microsoft.Extensions.AI 패키지의 AIFunctionFactory를 사용하여 도구가 정의됩니다. 각 도구에는 이름, 설명, 매개 변수 스키마 및 처리기 함수가 포함됩니다.

다중 모델 유연성

SDK는 하나의 AI 모델에 연결되지 않습니다. 여러 AI 모델을 지원하고 동적 모델 라우팅을 허용합니다. 예를 들어 동일한 애플리케이션 내에서 간단한 작업에 더 빠른 모델과 복잡한 추론을 위해 더 유능한 모델을 사용할 수 있습니다.

실시간 스트리밍

SDK는 스트리밍 응답을 지원합니다. 즉, AI가 출력을 생성할 때 앱으로 스트리밍할 수 있습니다. 예를 들어 토큰을 스트리밍하여 채팅 UI에 입력 표시기 또는 부분 대답을 표시할 수 있습니다. 이 동작은 환경을 보다 대화형으로 응답할 수 있게 합니다.

인증 및 보안

SDK는 다음과 같은 여러 인증 방법을 지원합니다.

  • GitHub 로그인 사용자: Copilot CLI 로그인에서 저장된 OAuth 자격 증명을 다시 사용합니다.
  • OAuth GitHub 앱: GitHub OAuth 앱에서 사용자 토큰을 전달합니다.
  • 환경 변수: 사용 COPILOT_GITHUB_TOKEN또는 GH_TOKENGITHUB_TOKEN.
  • BYOK(Bring Your Own Key) : GitHub 인증 없이 OpenAI, Azure AI Foundry 또는 Anthropic과 같은 공급자에 고유한 API 키를 사용합니다.

BYOK 옵션을 사용하지 않는 한 GitHub Copilot 구독이 필요합니다.

콘텐츠 관리

SDK는 세션 내에서 대화 기록을 자동으로 관리합니다. AI 모델에 일관된 다중 턴 상호 작용에 필요한 컨텍스트가 있도록 이전 메시지 및 도구 출력을 추적합니다. 긴 세션의 경우 SDK는 컨텍스트 창이 제한에 접근할 때 컨텍스트를 자동으로 압축하여 토큰 오버플로 오류를 방지하는 무한 세션 기능을 제공합니다.

핵심 개념

SDK의 핵심 개념을 이해하면 효과적으로 작업할 수 있습니다.

클라이언트

클래스는 CopilotClient Copilot CLI 서버에 대한 연결을 관리합니다. 애플리케이션에 대해 하나의 클라이언트 인스턴스를 만들고 이를 사용하여 세션을 만듭니다. 클라이언트는 CLI 프로세스 시작 및 중지, 통신 채널 설정 및 세션 수명 주기 관리를 처리합니다.

구성 옵션에는 (첫 번째 세션이 생성되면 자동으로 CLI 서버 시작), AutoStart (로깅 세부 정보 표시를 제어), LogLevel (CLI 실행 파일에 대한 사용자 지정 경로 지정) 및 CliPath (환경 변수 또는 CLI 로그인을 사용하는 대신 GitHub 토큰을 직접 제공)이 포함 GithubToken 됩니다.

Session

A CopilotSession 는 단일 대화 또는 작업 컨텍스트를 나타냅니다. 각 세션에는 고유한 대화 기록, 모델 구성, 도구 정의 및 시스템 프롬프트가 있습니다. 클라이언트 CreateSessionAsync에서 세션을 만들고, 메시지를 보내고, 이벤트 기반 모델을 통해 응답을 받습니다.

주요 세션 구성 옵션은 다음과 같습니다.

  • 모델: 사용할 AI 모델(예: gpt-4.1)입니다.
  • SystemMessage: SystemMessageConfig 개체와 Content 문자열을 사용하여 Mode (추가 또는 바꾸기) 방식으로 에이전트의 역할과 동작을 정의합니다.
  • 도구: 에이전트가 호출할 수 있는 사용자 지정 도구 정의입니다.
  • InfiniteSessions: 개체를 통한 자동 컨텍스트 압축을 InfiniteSessionConfig 제어합니다. 사용하도록 설정하면 BackgroundCompactionThreshold (백그라운드 압축을 트리거하는 컨텍스트 창 사용 비율) 및 BufferExhaustionThreshold (SDK가 토큰 오버플로를 방지하기 위해 압축을 강제하는 비율)을 구성할 수 있습니다.

도구

도구는 AI 에이전트가 추론 중에 호출할 수 있도록 세션에 등록하는 함수입니다. 각 도구에는 이름, 설명, 매개 변수 및 처리기 함수가 있습니다. AI 모델이 도구를 사용하기로 결정하면 SDK는 요청을 가로채고, 처리기를 호출하고, 추가 추론을 위해 결과를 모델에 다시 공급합니다.

.NET에서는 AIFunctionFactory.Create을 사용하여 Microsoft.Extensions.AI에서 도구를 정의합니다.

AIFunctionFactory.Create(
    async ([Description("The order ID number")] int orderId) =>
        await GetOrderDetailsAsync(orderId),
    "get_order_details",
    "Look up the status and details of a specific order.")

이벤트

SDK는 이벤트 기반 통신 모델을 사용합니다. 세션에 메시지를 보내면 처리가 수행되면 SDK에서 이벤트가 발생합니다.

  • AssistantMessageEvent: AI 모델은 완전한 응답을 생성했습니다.
  • AssistantMessageDeltaEvent: AI 모델은 스트리밍 중에 부분 응답 토큰을 생성했습니다. 속성에는 Data.DeltaContent 실시간으로 표시할 수 있는 증분 텍스트가 포함됩니다.
  • SessionIdleEvent: 세션 처리가 완료되었습니다(도구 호출 포함).
  • SessionErrorEvent: 처리하는 동안 오류가 발생했습니다.
  • ToolExecutionStartEvent 및 ToolExecutionCompleteEvent: 도구가 호출되었습니다.

이러한 이벤트를 구독하여 에이전트의 응답을 캡처하고 오류를 처리합니다. 비스트리밍 시나리오의 경우, 전체 응답을 수집하려면 AssistantMessageEvent을 사용하십시오. 스트리밍 시나리오(예: 채팅 UI에 입력 표시기 표시)의 경우 도착 시 토큰을 렌더링하는 데 사용합니다 AssistantMessageDeltaEvent .

세션 후크

SDK는 주요 지점에서 에이전트 동작을 가로채고 수정할 수 있는 후크를 제공합니다.

  • OnPreToolUse: 실행 전에 도구 호출을 가로챕니다. 처리기는 호출을 PermissionDecision 계속하거나, 통화를 차단하거나Allow, Deny 사용자에게 확인을 요청하는 값을Ask 반환합니다.
  • OnPostToolUse: 실행 후 도구 결과를 처리합니다. 모델에 도달하기 전에 결과를 로깅하거나 수정하는 데 유용합니다.
  • OnUserPromptSubmitted: 처리하기 전에 사용자 프롬프트를 가로채고 수정합니다.
  • OnErrorOccurred: 값을ErrorHandling 반환하여 Retry 오류를 처리하여 작업을 다시 시도하거나, 결과 없이 계속하거나Skip, Abort 처리를 중지합니다.
  • OnSessionStart: 세션이 시작될 때 실행되며 초기화 작업에 유용합니다.
  • OnSessionEnd: 세션이 종료되면 실행되며 정리 또는 로깅에 유용합니다.

이러한 후크를 사용하면 권한 제어, 로깅 및 안전 보호책을 구현할 수 있습니다.

.NET 개발을 위한 필수 구성 요소

.NET 애플리케이션에서 GitHub Copilot SDK를 사용하려면 환경에 다음이 필요합니다.

  • .NET 8.0 이상.
  • 시스템 PATH에 설치되고 사용할 수 있는 GitHub Copilot CLI입니다.
  • 활성 코필로트 구독(또는 BYOK에 대한 사용자 고유의 API 키)이 있는 GitHub 계정입니다.
  • GitHub.Copilot.SDK NuGet 패키지입니다.
  • Microsoft.Extensions.AI NuGet 패키지 (AIFunctionFactory를 사용하여 도구를 정의 위함).

요약

GitHub Copilot SDK는 애플리케이션에서 AI 에이전트를 빌드하기 위한 강력한 프로덕션 준비 플랫폼을 제공합니다. 에이전트 오케스트레이션, 도구 통합 및 컨텍스트 관리의 복잡성을 추상화하여 SDK를 통해 에이전트의 기능 및 비즈니스 논리를 정의하는 데 집중할 수 있습니다. 여러 언어, 실시간 스트리밍 및 유연한 인증 옵션을 지원하는 GitHub Copilot SDK는 다양한 애플리케이션에 AI 에이전트 기능을 추가하기 위한 다양한 선택입니다.