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` 후크 | 허용/거부/요청 |

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

특징	CLI 명령/옵션	Reason
세션 내보내기
파일로 내보내기

          `--share`, `/share` | 프로토콜에 없음 |

해결 방법

세션 내보내기

이 --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와 동등한 기능이 있습니다(위의 해결 방법 참조).
CLI를 직접 사용합니다. 일회성 작업의 경우 CLI를 호출합니다.
기능을 요청합니다.github/copilot-sdk 리포지토리에서 문제를 열어 프로토콜 지원을 요청합니다.

버전 호환성

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 전용)

해결 방법

세션 내보내기

권한 제어

토큰 사용량 추적

컨텍스트 압축

플랜 관리

메시지 조정

프로토콜 제한 사항

버전 호환성