GitHub Copilot 하네스

GitHub Copilot 하네스 (GitHub Copilot Harness)

GitHub Copilot 하네스 어댑터는 Agent Client Protocol(ACP)을 통해 HarnessAgent를 GitHub Copilot CLI에 연결해요. 어댑터는 ACP 설치, 세션, 스트리밍, 도구, 승인, 수명주기 관리를 @ai-sdk/harness-acp에 위임해요.

참고: 하네스 패키지는 실험적이에요. 이 초기 API가 더 다듬어지면서 릴리스 사이에 파괴적인 변경이 예상돼요.

출처: 문서

본문

셋업 (Setup)

npm install @ai-sdk/harness @ai-sdk/harness-github-copilot @ai-sdk/sandbox-vercel

ACP 하네스는 첫 세션이 시작될 때 샌드박스 안에 고정된 GitHub Copilot CLI를 설치해요. 호스트나 전역 설치 Copilot CLI를 절대 사용하지 않아요. 런치 명령은 GitHub Copilot의 자동 업데이트를 비활성화해서 설치된 버전이 그 부트스트랩 동안 고정 유지되게 해요.

Import

import {
  createGitHubCopilot,
  githubCopilot,
} from '@ai-sdk/harness-github-copilot';

githubCopilot은 기본 구성으로 createGitHubCopilot()을 호출한 것과 같아요.

기본 사용법 (Basic Usage)

import { HarnessAgent } from '@ai-sdk/harness/agent';
import { githubCopilot } from '@ai-sdk/harness-github-copilot';
import { createVercelNetworkSandboxSession } from '@ai-sdk/sandbox-vercel';

const agent = new HarnessAgent({
  harness: githubCopilot,
  model: 'gpt-5.5',
});

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  ports: [4000],
  template: await agent.getSandboxTemplate(),
});
const session = await agent.createSession({ sandboxSession });

let exitCode = 0;
try {
  const result = await agent.stream({
    session,
    prompt: 'Check the test failures and fix the production code.',
  });

  for await (const part of result.stream) {
    if (part.type === 'text-delta') {
      process.stdout.write(part.text);
    }
  }
} catch (err) {
  exitCode = 1;
  console.error(err);
} finally {
  await session.destroy();
  await sandboxSession.destroy();
  process.exit(exitCode);
}

이 에이전트를 Vercel Sandbox와 함께 사용하려면 호스트 환경에 VERCEL_OIDC_TOKEN과 authentication 아래 나열된 변수 중 하나를 제공하세요.

세션은 다중 턴, attach·detach, 콜드 스톱·재개, 턴 일시 중단·계속, 그리고 공유 ACP 브리지 수명주기를 통한 stopWhen 슬라이싱을 지원해요.

어댑터 설정 (Adapter Settings)

createGitHubCopilot()로 런타임을 구성하세요:

const harness = createGitHubCopilot({
  auth: 'ai-gateway',
  reasoningEffort: 'high',
  port: 4001,
  startupTimeoutMs: 180_000,
});

설정:

auth: auto, direct, ai-gateway 인증을 선택하거나 격리된 인증 환경을 받아요. 기본값은 auto로, Gateway 자격 증명이 있으면 AI Gateway를, 그렇지 않으면 직접 GitHub Copilot 인증을 선택해요.
credentialForwarding: 하네스 어댑터가 각 자격 증명을 샌드박스 프로세스로 전달하기 직전에 커스터마이즈하는 선택 동기/비동기 콜백. 그렇지 않으면 전달될 자격 증명 값(실제 자격 증명 또는 마스킹된 값)과 이를 노출하는 데 쓰는 환경 변수 이름을 받아요. 이 콜백은 샌드박스 프로세스로 전달되는 값만 제어해요. 하네스 어댑터가 호스트 프로세스에서 어떤 자격 증명을 발견·읽거나 접근할 수 있는지는 제한하지 않아요.
reasoningEffort: 추론 가능한 모델의 추론 노력. 지원 값: none, minimal, low, medium, high, xhigh, max. 생략하면 GitHub Copilot이 구성된 기본값을 사용해요.
mcpServers: 서버 이름별 ACP 네이티브 stdio, HTTP 또는 SSE MCP 서버 정의.
port: ACP 브리지 포트 재정의.
portEndpoint: 샌드박스 세션이 포트를 직접 노출할 수 없을 때 ACP 브리지의 호스트 엔드포인트.
startupTimeoutMs: ACP 브리지가 시작될 때까지 기다릴 최대 시간.
reconnect: 브리지 WebSocket 연결이 끊긴 후 재연결 타이밍. maxElapsedMs는 연결 설정과 백오프 지연을 포함한 전체 재시도 창을 제어하며 기본 30초. initialDelayMs 기본 50밀리초, maxDelayMs 기본 2초. 이 재시도는 지수 백오프를 사용하며 startupTimeoutMs와 별개예요. 샌드박스, 브리지 프로세스, 브리지 엔드포인트가 영구적으로 사용 불가하면 복구할 수 없어요.
mintBridgeToken: 샌드박스 id를 받고 ACP 브리지 인증 토큰을 반환하는 동기 함수. 기본적으로 어댑터는 무작위 32바이트 토큰을 생성해요. 커스텀 구현은 충분히 비밀인 토큰을 반환해야 해요.

reasoningEffort는 실행된 GitHub Copilot 서버에 고정되며 그것이 만드는 모든 세션에 적용돼요.

어댑터는 GitHub Copilot CLI, 실행 파일, 런치 명령, ACP 버전을 고정해요. 이 구현 세부사항은 createGitHubCopilot()로 재정의할 수 없어요.

인증 (Authentication)

GitHub Copilot은 직접 GitHub 인증과 AI Gateway 인증을 지원해요. 다음 환경 변수 중 하나 이상을 설정하세요:

COPILOT_GITHUB_TOKEN
GH_TOKEN
GITHUB_TOKEN
VERCEL_OIDC_TOKEN
AI_GATEWAY_API_KEY
AI_GATEWAY_BASE_URL

적용 가능한 자격 증명 환경 변수가 없으면, AI Gateway 인증이 선택되지 않는 한 어댑터는 호스트 시스템에서 네이티브 구독을 해결하려 시도해요.

직접 인증의 경우 GitHub Copilot은 나열된 순서로 세 가지 GitHub 토큰 변수를 확인해요. 파인 그레인드 개인 액세스 토큰은 Copilot Requests 권한이 필요하고, 클래식 개인 액세스 토큰은 지원되지 않아요. AI Gateway의 경우 어댑터는 VERCEL_OIDC_TOKEN 또는 AI_GATEWAY_API_KEY를 사용하고 AI_GATEWAY_BASE_URL을 존중해요.

샌드박스가 요청 변환을 지원하면 어댑터는 각 자격 증명을 일치하는 아웃바운드 요청에만 브로커링해요. 다른 샌드박스는 credentialForwarding을 적용한 후 직접 자격 증명 전달을 유지해요.

호스트가 런타임에 자격 증명을 해결할 때 인증 환경을 전달하세요:

const gatewayHarness = createGitHubCopilot({
  auth: {
    AI_GATEWAY_API_KEY: await resolveGatewayToken(),
    AI_GATEWAY_BASE_URL: 'https://ai-gateway.vercel.sh',
  },
});

제공된 record는 인증 발견을 위해 호스트 환경을 대체해요. 어댑터는 자격 증명을 process.env에 추가하거나 유지되는 ACP 수명주기 식별자에 그 값을 포함하지 않아요.

두 종류의 자격 증명이 모두 있을 때 특정 인증 경로를 강제하세요:

const directHarness = createGitHubCopilot({ auth: 'direct' });
const gatewayHarness = createGitHubCopilot({ auth: 'ai-gateway' });

AI Gateway 모델 요청은 GitHub 인증을 요구하지 않지만, 내장 GitHub MCP 기능은 요구해요.

샌드박스 (Sandbox)

GitHub Copilot은 @ai-sdk/harness-acp를 통해 샌드박스 안에서 실행돼요. 노출된 포트가 하나 이상 있는 네트워크 샌드박스가 필요해요:

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  ports: [4000],
  template: await agent.getSandboxTemplate(),
});

첫 세션은 GitHub Copilot CLI를 설치하려면 네트워크 이그레스가 필요해요. 이후 모델, GitHub, 웹, MCP 요청도 네트워크 접근이 필요해요.

내장 도구 (Built-in Tools)

어댑터는 bash, grep, glob을 해당하는 공통 하네스 도구로 매핑해요.

다른 도구는 네이티브 GitHub Copilot 이름으로 계속 사용할 수 있어요. read_bash, stop_bash, list_bash, view, create, edit, web_fetch, skill, sql, 에이전트 도구, task가 포함돼요. GitHub 및 사용자 구성 MCP 도구는 동적으로 유지돼요.

공유 ACP 하네스는 GitHub Copilot이 권한 요청을 보낼 때 구성된 Harness permissionMode를 적용해요. allow-reads는 읽기 연산을 승인하고, allow-edits는 파일 수정도 승인하며, allow-all은 모든 요청을 승인해요. 셸 실행은 allow-edits에서도 여전히 승인이 필요해요.

알려진 제한 (Known Limitations)

ACP v1은 모든 네이티브 도구 이벤트에 안정적인 프로그램적 이름을 노출하지 않아요. 어댑터는 표준 title, kind, schema 일치를 사용하고 일치하지 않는 도구는 동적으로 남겨요.
ACP v1은 모델 스텝 경계나 스텝별 사용량을 노출하지 않아요. 어댑터는 경계를 추론하고 GitHub Copilot이 합계를 제공하지 않을 때 알 수 없는 스텝별 사용량을 보고해요.
ACP v1에는 휴대 가능한 수동 압축 또는 미드 턴 스티어링 API가 없어요.
ACP v1에는 휴대 가능한 내장 도구 필터링 API가 없어요. 호스트 도구 필터링은 지원되지만 GitHub Copilot 내장 도구를 필터링하면 지원되지 않는 역량 오류가 throw돼요.
GitHub Copilot은 현재 내장 도구 승인 요청을 지원하지 않아요. 이 어댑터로 permissionMode: 'allow-all'를 사용하세요. 호스트 실행 AI SDK 도구 승인은 여전히 작동해요.
GitHub Copilot ACP는 구조화 출력 메타데이터 매핑을 노출하지 않으므로 스키마 기반 구조화 출력은 지원되지 않아요.
GitHub Copilot ACP는 질문 도구를 노출하지 않으므로 askUserQuestions는 지원되지 않아요.
GitHub Copilot CLI는 어떤 모델에 대해서도 ACP를 통해 추론 콘텐츠를 표면화하지 않아요. reasoningEffort는 추론 깊이를 제어하지, 가시성을 제어하지 않아요. 추론 요약을 emit하는 것은 ACP의 session/new와 session/set_config_option(mode, model, reasoning_effort, allow_all, agent로 제한)이 클라이언트에 노출하지 않는 파라미터가 필요해요. 이를 설정하는 유일한 코드 경로는 GitHub Copilot의 대화형 터미널 UI에 있는데, 이는 헤드리스 --acp --stdio 모드에서 실행되지 않아요.
커스텀 headers는 네이티브로 지원되지 않고 샌드박스 외부 요청 변환을 통해서만 적용돼요. 그 역량이 없는 샌드박스가 제공되면 커스텀 headers를 전달할 수 없어 무시돼요.

GitHub Copilot 하네스