이 레포가 무엇을 하는 물건인가.
구조는 단순명료합니다: 내 앱 → SDK 클라이언트 → (JSON-RPC) → 서버 모드로 도는 Copilot CLI. SDK가 CLI 프로세스의 생명주기를 자동 관리하므로, 개발자는 세션을 열고 프롬프트를 보내고 스트리밍 이벤트를 받는 코드만 씁니다. 계획 수립·도구 실행·파일 편집·권한 게이트는 CLI 엔진의 몫.
Claude Agent SDK가 연 "코딩 에이전트의 SDK화" 흐름에 GitHub이 응답한 형태로, 차별점은 언어 폭입니다 — Node·Python뿐 아니라 Go·.NET·Java·Rust까지 1급 지원해, 엔터프라이즈 백엔드(Java/.NET) 안에 에이전트를 심는 시나리오를 정조준합니다.
트렌딩 이유 · 경쟁 대비 장점.
"앱에 에이전트 심기"가 2026년의 기본 요구가 되면서, 선택지는 ① 직접 오케스트레이션 구축(도구 루프·권한·세션 관리 전부 자작) ② 에이전트 SDK 차용으로 갈립니다. Copilot SDK는 후자 진영에서 "이미 수백만 명이 쓰는 CLI 엔진을 그대로 노출한다"는 검증성과, BYOK(자기 키 지참) 지원으로 GitHub 인증 없이도 쓸 수 있는 유연성을 무기로 삼습니다.
| 비교 항목 | 자작 오케스트레이션 | Copilot SDK |
|---|---|---|
| 도구 루프·계획 | 직접 구현 (수개월) | CLI 엔진 내장 — 호출만 |
| 언어 지원 | 내 스택 한정 | TS·Python·Go·.NET·Java·Rust 공식 6종 |
| 인증 | 직접 설계 | GitHub OAuth·토큰·BYOK(OpenAI/Anthropic/Azure 키) 4경로 |
| 고급 기능 | 전부 자작 | 훅·커스텀 에이전트·MCP·스킬·세션 영속·fleet 모드 문서화 |
표준 사용은 Copilot 구독 필수(무료 티어 있음)이고 프롬프트마다 프리미엄 요청 쿼터를 씁니다. BYOK면 GitHub 인증 없이 자기 LLM 키로 — 단 키 기반 인증만 지원(Entra ID·관리 ID 불가). 비용 모델을 먼저 따져볼 것.
루트의 sdk-protocol-version.json과 codegen 스크립트가 6개 SDK의 일관성을 기계적으로 유지합니다 — 멀티 언어 SDK 운영의 정석 풍경.
하나의 프로토콜, 여섯 개의 클라이언트.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 엔진 | Copilot CLI (서버 모드) | 계획·도구 호출·파일 편집·권한 처리 — SDK는 이걸 원격 조종. |
| 프로토콜 | JSON-RPC + sdk-protocol-version.json | 클라이언트↔CLI 통신 규약. 버전 파일로 6개 SDK 동기화. |
| SDK 6종 | nodejs/·python/·go/·dotnet/·java/·rust/ | 각 언어 관용구로 같은 표면 노출 (CopilotClient·Session·ToolSet…). |
| 번들링 | Node·Python·.NET은 CLI 자동 동봉 | 별도 설치 불필요. Go·Java·Rust는 PATH의 CLI 사용(앱 레벨 번들 옵션도). |
| 코드 생성 | scripts/codegen | 프로토콜 정의에서 언어별 타입 생성 — 드리프트 방지. |
| 테스트 | test/harness + snapshots (377 파일) | 언어 공통 시나리오를 스냅샷으로 교차 검증. |
| 기능 문서 | docs/features/ 14편 | 훅·커스텀 에이전트·MCP·스킬·세션 영속·fleet 모드·스트리밍·이미지 입력…. |
앱의 프롬프트 하나가 파일 편집으로 끝나기까지.
설계에서 곱씹을 지점은 ④ 권한 핸들러입니다. 기본값은 CLI의 --allow-all과 비슷하게 1급 도구가 다 열려 있지만, 모든 도구 실행이 SDK의 permission handler를 거치므로 앱이 도구 호출을 승인·거부·변형하는 정책 코드를 쓸 수 있습니다 — "에이전트에게 자율을 주되 고삐는 앱이 쥔다"의 구현 지점입니다. 훅(hooks.md)·조향과 큐잉(steering-and-queueing.md)·fleet 모드(에이전트 함대 운용) 같은 고급 기능도 같은 통로 위에 얹힙니다.
Copilot CLI가 숙련된 프리랜서라면, SDK는 그 프리랜서를 내 회사 결재 시스템에 연결하는 계약서입니다. 일하는 방식(계획·도구 사용)은 프리랜서의 노하우 그대로 쓰되, 비용이 드는 행동(파일 수정·외부 호출)마다 우리 회사 결재(권한 핸들러)를 거치게 하는 거죠.
어떤 폴더가 무슨 일을 하나.
| 위치 | 주목할 점 |
|---|---|
docs/features/ | 기능 14편이 사실상 "임베디드 에이전트 설계 교과서" — agent-loop부터 fleet-mode까지. |
test/harness + snapshots | 6개 언어가 같은 시나리오에서 같은 결과를 내는지 스냅샷으로 잠금 — 멀티 SDK 품질 관리의 핵심 장치. |
sdk-protocol-version.json | 프로토콜 버전의 단일 진실원 — SDK·CLI 호환성의 닻. |
nodejs/src (Canvas) | 캔버스(구조화 UI 액션) 같은 신기능이 노출되는 표면 — API 진화를 관찰하기 좋은 지점. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
엔진을 라이브러리로 다시 짜는 대신 검증된 CLI를 JSON-RPC 서버로 돌리고 클라이언트만 6벌 만드는 구조 — LSP가 에디터 생태계에서 증명한 패턴의 에이전트판입니다.
6개 언어 SDK가 어긋나지 않게 유지하는 3종 장치(scripts/codegen·sdk-protocol-version.json·test/snapshots)는 사내 멀티 언어 클라이언트를 운영하는 팀에 그대로 이식할 만한 체계입니다.
"기본은 다 허용하되 모든 호출이 앱의 핸들러를 통과한다"는 설계는 에이전트 제품의 안전 장치 설계에 좋은 참조입니다. 각 SDK의 권한 콜백 시그니처를 비교해 보세요.
docs/auth/는 "구독 기반 vs 자기 키" 시나리오를 가르는 기준(비용·기업 정책·지원 모델 차이)을 명확히 문서화 — API 제품의 인증 메뉴 설계 견본.
돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| 계정 | Copilot 구독(무료 티어 포함) 또는 BYOK용 LLM API 키(OpenAI·Anthropic·Azure AI Foundry). |
| CLI | Node·Python·.NET SDK는 자동 번들. Go·Java·Rust는 copilot CLI를 PATH에 (또는 앱 레벨 번들). |
| 설치 | npm i @github/copilot-sdk / pip install github-copilot-sdk / cargo·go get·NuGet·Maven. |
| 비용 인지 | 프롬프트당 프리미엄 요청 쿼터 차감 — 대량 자동화 전 빌링 모델 확인. |
난이도별로 손에 익히는 단계.
Node SDK로 클라이언트 생성 → 세션 → "이 폴더의 TODO 주석을 모아줘" 프롬프트 → 스트리밍 이벤트를 콘솔에 찍어 봅니다. Getting Started 가이드 그대로.
파일 쓰기 도구만 사용자 승인을 요구하고 읽기는 자동 허용하는 permission handler를 구현해, 에이전트가 편집을 시도할 때 앱이 개입하는 흐름을 만들어 봅니다.
GitHub 인증 없이 자기 LLM 키로 SDK를 구동해 보고(docs/auth/byok.md), 모델 목록 API로 런타임에 사용 가능 모델을 조회합니다.
같은 시나리오(파일 분석 작업)를 Python과 Go SDK로 각각 구현해 이벤트 시퀀스를 비교하고, test/harness가 이 동등성을 어떻게 기계 검증하는지 읽어 봅니다.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 구조 이해 + 첫 세션 | docs/getting-started.md · 실습 1 |
| 2주차 | 기능 문서 일주 — 훅·MCP·스킬·세션 영속 | docs/features/ 14편 |
| 3주차 | 권한·인증 설계 | docs/auth/ · 실습 2~3 |
| 4주차 | 쿡북 레시피 실전 | awesome-copilot cookbook |
| 5주차 | 비교 연구 — Claude Agent SDK와 표면 대조 | 양쪽 문서 · 실습 4 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| JSON-RPC | JSON으로 원격 함수를 호출하는 경량 프로토콜 — SDK↔CLI의 언어. |
| 서버 모드 | Copilot CLI가 대화형 대신 RPC 서버로 도는 모드. |
| BYOK | Bring Your Own Key — GitHub 인증 없이 자기 LLM API 키로 사용. |
| permission handler | 도구 실행을 앱이 승인/거부/변형하는 콜백 — 통제의 핵심. |
| 프리미엄 요청 | Copilot 빌링 단위 — SDK 프롬프트도 동일 차감. |
| 세션 영속 | 에이전트 대화 상태를 저장해 이어가는 기능 (session-persistence). |
| fleet 모드 | 여러 에이전트를 묶어 운용하는 기능 — features 문서 참조. |
| codegen | 프로토콜 정의에서 언어별 타입을 자동 생성 — SDK 드리프트 방지. |
| 스냅샷 테스트 | 출력 결과를 파일로 저장해 회귀를 잡는 기법 — 6개 SDK 교차 검증에 사용. |
| GA | Generally Available — 정식 출시, 시맨틱 버저닝 적용. |