SDK 및 CLI 호환성

참고

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

          GitHub Copilot SDK 는 JSON-RPC 프로토콜을 GitHub Copilot 명령 줄 인터페이스 (CLI) 통해 통신합니다. 기능을 SDK에서 사용할 수 있도록 이 프로토콜을 통해 명시적으로 노출해야 합니다. 많은 대화형 CLI 기능은 터미널별로 제공되며 프로그래밍 방식으로 사용할 수 없습니다.

기능 비교

SDK에서 사용 가능

특징	SDK 메서드	Notes

          **세션 관리** |

| | | 세션 만들기 | createSession() | 전체 구성 지원 | | 세션 다시 시작 | resumeSession() | 무한 세션 작업 영역 사용 | | 세션 연결 끊기 | disconnect() | 메모리 내 리소스 해제 | | 세션 삭제 | destroy() | 대신 disconnect()를 사용하세요. | | 세션 삭제 | deleteSession() | 스토리지에서 제거 | | 세션 목록 표시 | listSessions() | 저장된 모든 세션 | | 마지막 세션 가져오기 | getLastSessionId() | 빠른 다시 시작 | | 포그라운드 세션 가져오기 | getForegroundSessionId() | 다중 세션 조정 | | 포그라운드 세션 설정 | setForegroundSessionId() | 다중 세션 조정 | | 메시지 | | | | 메시지 보내기 | send() | 첨부 파일 포함 | | 보내기 및 대기 | sendAndWait() | 완료될 때까지 차단 | | 조향(직접 실행 모드) | send({ mode: "immediate" }) | 중단 없이 중간 턴 삽입 | | 큐잉(등록 모드) | send({ mode: "enqueue" }) | 순차적 처리를 위한 버퍼(기본값) | | 첨부 파일 | send({ attachments: [{ type: "file", path }] }) | 이미지 자동 인코딩 및 크기 조정 | | 디렉터리 첨부 파일 | send({ attachments: [{ type: "directory", path }] }) | 디렉터리 컨텍스트 연결 | | 기록 가져오기 | getMessages() | 모든 세션 이벤트 | | 중지 | abort() | 기내 요청 취소 | | Tools | | | | 사용자 지정 도구 등록 | registerTools() | 전체 JSON 스키마 지원 | | 도구 권한 제어 | onPreToolUse 후크 | 허용/거부/요청 | | 도구 결과 수정 | onPostToolUse 후크 | 결과 변환 | | 사용 가능한/제외된 도구 | availableTools, excludedTools 구성 | 필터 도구 | | 모델 | | | | 모델 나열 | listModels() | 기능, 청구, 정책 | | 모델 설정(생성 시) | model 세션 구성에서 | 세션당 | | 모델 전환(세션 중) | session.setModel() | 또한 다음을 통해 session.rpc.model.switchTo() | | 현재 모델 가져오기 | session.rpc.model.getCurrent() | 활성 모델 검색 | | 추론 노력 | reasoningEffort 구성 | 지원되는 모델의 경우 | | 에이전트 모드 | | | | 현재 모드 가져오기 | session.rpc.mode.get() | 현재 모드를 반환합니다. | | 모드 설정 | session.rpc.mode.set() | 모드 간 전환 | | 계획 관리 | | | | 계획 읽기 | session.rpc.plan.read() | plan.md 콘텐츠 및 경로 가져오기 | | 계획 업데이트 | session.rpc.plan.update() | plan.md 콘텐츠 작성 | | 계획 삭제 | session.rpc.plan.delete() | plan.md 제거 | | 작업 영역 파일 | | | | 작업 영역 파일 나열 | session.rpc.workspace.listFiles() | 세션 작업 영역의 파일 | | 작업 영역 파일 읽기 | session.rpc.workspace.readFile() | 파일 콘텐츠 읽기 | | 작업 영역 파일 만들기 | session.rpc.workspace.createFile() | 작업 영역에서 파일 만들기 | | ** 인증** | | | | 인증 상태 가져오기 | getAuthStatus() | 로그인 상태 확인 | | 토큰 사용 | githubToken 옵션 | 코드 기반 인증 | | 인터넷 | | | | 핑 | client.ping() | 서버 타임스탬프를 사용하여 상태 검사 | | 서버 상태 가져오기 | client.getStatus() | 프로토콜 버전 및 서버 정보 | | MCP 서버 | | | | 로컬/stdio 서버 | mcpServers 구성 | 프로세스 생성하기 | | 원격 HTTP/SSE | mcpServers 구성 | 서비스에 연결 | | 후크 | | | | 사전 도구 사용 | onPreToolUse | 권한, 인수 수정 | | 사후 도구 사용 | onPostToolUse | 결과 수정 | | 사용자 프롬프트 | onUserPromptSubmitted | 프롬프트 수정 | | 세션 시작/종료 | onSessionStart, onSessionEnd | 원본/이유가 있는 수명 주기 | | 오류 처리 | onErrorOccurred | 사용자 지정 처리 | | Events | | | | 모든 세션 이벤트 | on(), once() | 40개 이상의 이벤트 유형 | | 스트리밍 | streaming: true | 델타 이벤트 | | 세션 구성 | | | | 사용자 지정 에이전트 | customAgents 구성 | 특수 에이전트 정의 | | 시스템 메시지 | systemMessage 구성 | 추가 또는 바꾸기 | | 사용자 지정 공급자 | provider 구성 | BYOK 지원 | | 무한 세션 | infiniteSessions 구성 | 자동 압축 | | 권한 처리기 | onPermissionRequest | 요청 승인/거부 | | 사용자 입력 처리기 | onUserInputRequest | ask_user 처리 | | 기술 | skillDirectories 구성 | 사용자 지정 기술 | | 비활성화된 기술 | disabledSkills 구성 | 특정 기술 사용 안 함 | | 구성 디렉터리 | configDir 구성 | 기본 구성 위치 재정의 | | 클라이언트 이름 | clientName 구성 | User-Agent에서 앱 식별 | | 작업 디렉터리 | workingDirectory 구성 | 세션 cwd 설정 | | 실험적 | | | | 에이전트 관리 | session.rpc.agent.* | 에이전트 나열, 선택, 선택 취소, 현재 에이전트 가져오기 | | 플릿 모드 | session.rpc.fleet.start() | 병렬 하위 에이전트 실행 | | 수동 압축 | session.rpc.compaction.compact() | 요청 시 압축 실행 |

SDK에서 사용할 수 없음(CLI 전용)

특징	CLI 명령/옵션	Reason

          **세션 내보내기** |

해결 방법

세션 내보내기

이 --share 옵션은 SDK를 통해 사용할 수 없습니다. 이 문제의 해결 방법:

        **수동으로 이벤트 수집:** 세션 이벤트에 구독하고 내보내기 기능을 직접 설정합니다.

TypeScript

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getMessages();
// Format as markdown yourself

const events: SessionEvent[] = [];
session.on((event) => events.push(event));
// ... after conversation ...
const messages = await session.getMessages();
// Format as markdown yourself

        **CLI를 직접 사용하여** 일회성 내보내기를 수행합니다.

권한 제어

SDK는 기본적으로 거부 권한 모델을 사용합니다. 앱에서 처리기를 제공하지 onPermissionRequest 않는 한 모든 권한 요청(파일 쓰기, 셸 명령, URL 페치 등)이 거부됩니다.

          `--allow-all-paths` 또는 `--yolo` 대신에 사용 권한 처리기를 사용하십시오.

TypeScript

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

const session = await client.createSession({
  onPermissionRequest: approveAll,
});

토큰 사용량 추적

대신 /usage를 사용하기보다 사용 이벤트에 가입하세요.

TypeScript

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

session.on("assistant.usage", (event) => {
  console.log("Tokens used:", {
    input: event.data.inputTokens,
    output: event.data.outputTokens,
  });
});

컨텍스트 압축

대신 /compact자동 압축을 구성하거나 수동으로 실행합니다.

TypeScript

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

// Automatic compaction via config
const session = await client.createSession({
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // Start background compaction at 80% context utilization
    bufferExhaustionThreshold: 0.95,      // Block and compact at 95% context utilization
  },
});

// Manual compaction (experimental)
const result = await session.rpc.compaction.compact();
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);

참고

임계값은 절대 토큰 수가 아닌 컨텍스트 사용률(0.0-1.0)입니다.

플랜 관리

프로그래밍 방식으로 세션 계획을 읽고 씁니다.

TypeScript

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

// Read the current plan
const plan = await session.rpc.plan.read();
if (plan.exists) {
  console.log(plan.content);
}

// Update the plan
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });

// Delete the plan
await session.rpc.plan.delete();

메시지 조정

중단하지 않고 현재 LLM 턴에 메시지를 삽입합니다.

TypeScript

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

// Steer the agent mid-turn
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });

// Default: enqueue for next turn
await session.send({ prompt: "Next, add tests" });

프로토콜 제한 사항

SDK는 CLI의 JSON-RPC 프로토콜을 통해서만 노출되는 기능에 액세스할 수 있습니다. 사용할 수 없는 CLI 기능이 필요한 경우:

        **대체 항목 확인:** 많은 기능에는 SDK와 동등한 기능이 있습니다(위의 [해결 방법](#workarounds) 참조).

        **CLI를 직접 사용합니다.** 일회성 작업의 경우 CLI를 호출합니다.

        **기능을 요청합니다.**[github/copilot-sdk](https://github.com/github/copilot-sdk/issues) 리포지토리에서 문제를 열어 프로토콜 지원을 요청합니다.

버전 호환성

SDK 프로토콜 범위	CLI 프로토콜 버전	Compatibility
v2-v3	v3	전체 지원
v2-v3	v2	자동 v2 어댑터에서 지원됨

SDK는 시작 시 CLI와 프로토콜 버전을 협상합니다. SDK는 프로토콜 버전 2~3을 지원합니다. SDK는 v2 CLI 서버에 연결할 때 tool.call 및 permission.request 메시지를 v3 이벤트 모델에 자동으로 적응시켜 코드 변경이 필요하지 않습니다.

런타임에 버전을 확인할 수 있습니다.

TypeScript

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

const status = await client.getStatus();
console.log("Protocol version:", status.protocolVersion);

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

이 기사에서

기능 비교

SDK에서 사용 가능

SDK에서 사용할 수 없음(CLI 전용)

해결 방법

세션 내보내기

권한 제어

토큰 사용량 추적

컨텍스트 압축

플랜 관리

메시지 조정

프로토콜 제한 사항

버전 호환성