728x90

1. 개념

GitHub에서 출시한 GitHub Copilot SDK는 Copilot CLI의 핵심 루프(계획 수립, 도구 호출, 파일 편집, 명령 실행)를 개발자의 애플리케이션에 직접 통합할 수 있게 해주는 도구입니다.

  • 핵심 가치: 에이전트의 뇌(LLM)뿐만 아니라 손발(Executor) 역할을 하는 인프라(계획 루프, 도구 실행기, 컨텍스트 관리, 오류 처리)를 직접 구현할 필요없이 즉시 활용 가능합니다.
  • 통신 구조: SDK는 JSON-RPC를 통해 Copilot CLI 서버와 통신하며 라이프사이클을 자동 관리합니다.
    • [Architecture Flow]
      나의 Application → SDK Client → (JSON-RPC) → Copilot CLI (Server Mode)
  • 지원 환경: Python, Node.js/TypeScript, Go, .NET
  • 인증 방식: * GitHub Copilot 구독 기반 (BPM Plus 신청)
    • BYOK(Bring Your Own Key): GitHub 인증 없이도 지원되는 LLM Provider(OpenAI, Anthropic 등)의 API Key를 설정하여 독립적으로 사용 가능 (관련 링크)
      • 이 경우에도 구독은 필요합니다.

2. 시작하기 (Setup)

Copilot CLI 서버와 SDK를 순차적으로 설치합니다. (Node.js 22 이상 권장)

CLI 설치 및 인증

# npm으로 전역 설치
npm install -g @github/copilot 

# 설치 확인
copilot --version

# 인증 (로그인 커맨드 또는 환경변수 설정) 
copilot /login # github.com 선택하여 로그인합니다. -> 로그인 시, ZTNA 연결 필요!
  • 환경 변수 우선순위: COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN

SDK 설치 (Python 기준)

pip install github-copilot-sdk
  • SDK까지 설치했음에도 예제 코드 실행 시, 해당 패키지를 찾을 수 없다는 오류가 발생한다면 PATH 문제이므로 재확인 필요.

3. 예제 코드

A. 기본 채팅 및 세션 관리

import asyncio
from copilot import CopilotClient

async def main():
    client = CopilotClient() 
    await client.start() 
    session = await client.create_session({"model": "gpt-4.1"}) 
    response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
    print(response.data.content)

await client.stop()
asyncio.run(main())
python main.py

B. Custom Tool 사용법

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

// Copilot이 호출 가능한 툴 함수 정의
const getWeather = defineTool("get_weather", {
    description: "Get the current weather for a city",
    parameters: {
        type: "object",
        properties: {
            city: { type: "string", description: "The city name" },
        },
        required: ["city"],
    },
    handler: async (args: { city: string }) => {
        const { city } = args;
        // In a real app, you'd call a weather API here
        const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"];
        const temp = Math.floor(Math.random() * 30) + 50;
        const condition = conditions[Math.floor(Math.random() * conditions.length)];
        return { city, temperature: `${temp}°F`, condition };
    },
});

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    streaming: true,
    tools: [getWeather], # 사용자 정의 도구(Tool) 지정
});

session.on("assistant.message_delta", (event) => {
    process.stdout.write(event.data.deltaContent);
});

session.on("session.idle", () => {
    console.log(); // New line when done
});

await session.sendAndWait({
    prompt: "What's the weather like in Seattle and Tokyo?",
});

await client.stop();
process.exit(0);

C. MCP 서버 연결

사내 지식 베이스나 외부 도구를 MCP 규격으로 연결하여 에이전트의 지식 범위를 확장할 수 있습니다.

const session = await client.createSession({
    mcpServers: {
        github: {
            type: "http",
            url: "https://api.githubcopilot.com/mcp/",
        },
    },
});

4. MAF에서 GitHub Copilot SDK를 사용하기

Microsoft Agent Framework(MAF)는 GitHub Copilot SDK를 백엔드로 사용하는 에이전트 만들기를 지원합니다.

먼저, Microsoft Agent Framework GitHub Copilot 패키지를 설치합니다.

pip install agent-framework-github-copilot --pre
  • 반드시 --pre 옵션으로 설치해야 합니다.

A. 기본 에이전트 만들기

import asyncio
from agent_framework.github import GitHubCopilotAgent, GitHubCopilotOptions

async def basic_example():
    agent = GitHubCopilotAgent(
        default_options={
            "instructions": "You are a helpful assistant.",
            "model": "gpt-5",
            "timeout": 120,
        },
    )

    async with agent:
        result = await agent.run("What is Microsoft Agent Framework?")
        print(result)

B. Tool 사용법

에이전트에 사용자 지정 함수를 도구로 줄 수 있습니다.

from typing import Annotated
from pydantic import Field

def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny with a high of 25C."

async def tools_example():
    agent = GitHubCopilotAgent(
        default_options={"instructions": "You are a helpful weather agent."},
        tools=[get_weather],  # 사용자 정의 도구(Tool) 지정
    )

    async with agent:
        result = await agent.run("What's the weather like in Seattle?")
        print(result)

💡 의견

LangGraph가 자유도 높은 ‘화이트박스형’ 설계에 유리하다면, GCK(GitHub Copilot SDK)는 검증된 고성능 에이전트를 내 앱의 서브 에이전트로 즉시 편입시킬 수 있는 완성형 엔진에 가깝습니다.

  1. Copilot을 컴포넌트로 활용

GCK의 최대 강점은 GitHub Copilot을 내 애플리케이션의 독립적인 서브 에이전트(Sub-agent)로 통합할 수 있다는 점입니다. 복잡한 오케스트레이션을 직접 설계하는 대신, 검증된 Copilot의 추론 모델과 컨텍스트 관리 능력을 하나의 기능 단위(Component)로 가져와 쓸 수 있어 아키텍처가 단순해집니다.

  1. 운영 안정성 및 리스크 관리
  • 인프라 내장: 파일 수정, CLI 실행, 보안 권한, 웹 서치 등 에이전트 구동에 필요한 ‘손발’이 이미 규격화되어 제공됩니다.
  • 리스크 관리: LangGraph에서 쉽게 발생가능한 상태 오염(State Pollusion)이나 무한 루프 등의 설계 결함을 프레임워크 수준에서 방어해 주므로, 개발자는 도구(Tool) 정의와 비지니스 로직에만 집중할 수 있습니다.
  1. GCK의 한계
    • Structured output 미지원
    • 아직 Preview 상태
    • 공식 문서 부족

요약

  • LangGraph: 아키텍처를 밑바닥부터 제어해야 하는 복잡한 에이전트에 적합.
  • GCK: 개발 워크플로우를 혁신하는 에이전트를 빠르게 제품화하고, Copilot의 강력한 인프라를 서브 에이전트로 즉시 활용하고자 할 때 최적.

5. 참고 링크

728x90
저작자표시 (새창열림)

'💻 Study > 🤖 AI 인공지능' 카테고리의 다른 글

Batch 배치  (0) 2024.09.24
Linear Layer  (0) 2024.06.20
Basic Building Block 기본 빌딩 블록  (0) 2024.06.20

티스토리툴바