Cursor 하네스

Cursor 하네스 (Cursor Harness)

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

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

출처: 문서

본문

셋업 (Setup)

npm install @ai-sdk/harness @ai-sdk/harness-cursor @ai-sdk/sandbox-vercel

Cursor 사용자 API 키를 만들고 CURSOR_API_KEY를 설정하세요. 이 키는 Cursor가 모델 provider에 인증하는 방식과 무관하게 샌드박스에서 Cursor CLI를 인증해요.

어댑터는 첫 세션이 시작될 때 공식 Cursor 설치 명령으로 샌드박스 안에 Cursor CLI를 설치해요.

Import

import { createCursor, cursor } from '@ai-sdk/harness-cursor';

cursor는 기본 구성으로 createCursor()를 호출한 것과 같아요.

기본 사용법 (Basic Usage)

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

const agent = new HarnessAgent({
  harness: cursor,
  model: 'gpt-5.6-luna',
});

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

try {
  const result = await agent.generate({
    session,
    prompt: 'Inspect this project and summarize its purpose.',
  });
  console.log(result.text);
} finally {
  await session.destroy();
  await sandboxSession.destroy();
}

이 에이전트를 Vercel Sandbox와 함께 사용하려면 호스트 환경에 VERCEL_OIDC_TOKEN과 CURSOR_API_KEY를 제공하세요.

어댑터 설정 (Adapter Settings)

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

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

설정:

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

어댑터는 설치 명령과 ACP 런치 명령을 고정해요. 이 구현 세부사항은 createCursor()로 재정의할 수 없어요.

인증 (Authentication)

Cursor에는 두 개의 독립된 인증 계층이 있어요:

CURSOR_API_KEY는 Cursor CLI를 Cursor 계정에 인증해요. 하네스는 모든 auth 모드에서 이 키를 요구해요.
Cursor의 계정 설정이 Cursor가 모델 provider에 인증하는 방식을 결정해요. 하네스는 이 설정을 읽거나 바꿀 수 없어요.

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

직접 라우팅의 경우 Cursor에서 모델 provider를 구성하세요. AI Gateway의 경우 Cursor 설정에서 Cursor의 OpenAI API 키를 AI Gateway API 키로 구성하고 Override OpenAI Base URL을 https://ai-gateway.vercel.sh/cursor/v1로 설정하세요. Cursor는 계정 구성에서 그 자격 증명을 해결해요. 하네스는 모델 provider 인증에 AI_GATEWAY_API_KEY나 VERCEL_OIDC_TOKEN을 사용하지 않아요.

명시적 direct와 ai-gateway 값은 선택한 경로를 Cursor에서 구성해야 한다는 경고를 emit해요. auto는 경고 없이 받아들여져요:

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

process.env를 변경하거나 읽지 않고 프로그램적으로 해결된 Cursor 계정 자격 증명을 제공하세요:

const harness = createCursor({
  auth: { CURSOR_API_KEY: await resolveCursorToken() },
});

이 record는 Cursor CLI 인증만 구성해요. Cursor의 계정 설정이 여전히 모델 provider 라우팅을 제어해요.

샌드박스 (Sandbox)

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

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

첫 세션은 Cursor의 공식 설치 프로그램을 실행하려면 네트워크 이그레스가 필요해요.

내장 도구 (Built-in Tools)

어댑터는 Cursor의 터미널, glob, grep 도구를 공통 bash, glob, grep 도구로 매핑해요. 또한 Cursor의 나머지 내장 도구를 안정적인 이름으로 노출하는데, read, edit, ls, semanticSearch, webSearch, task, 그리고 Cursor의 플래닝·MCP·브라우저·환경 도구가 포함돼요.

Cursor 호스트 도구 호출은 ACP MCP 전송을 사용해요. 어댑터는 Cursor의 MCP 페이로드를 인식하고 호출을 호스트 측 도구 실행과 연관 지어요.

알려진 제한 (Known Limitations)

Cursor의 모델 provider 인증 경로는 Cursor에서 구성해야 해요. auth 어댑터 설정은 이를 프로그램적으로 전환할 수 없어요.
ACP v1은 모델 스텝 경계나 스텝별 사용량을 노출하지 않아요. 어댑터는 경계를 추론하고 Cursor가 합계를 제공하지 않을 때 알 수 없는 스텝별 사용량을 보고해요.
ACP v1에는 휴대 가능한 수동 압축 또는 미드 턴 스티어링 API가 없어요.
ACP v1에는 휴대 가능한 내장 도구 필터링 API가 없어요. 호스트 도구 필터링은 지원되지만 Cursor 내장 도구를 필터링하면 지원되지 않는 역량 오류가 throw돼요.
Cursor는 현재 내장 도구 승인 요청을 지원하지 않아요. 이 어댑터로 permissionMode: 'allow-all'를 사용하세요. 호스트 실행 AI SDK 도구 승인은 여전히 작동해요.
Cursor ACP는 구조화 출력 메타데이터 매핑을 노출하지 않으므로 스키마 기반 구조화 출력은 지원되지 않아요.
커스텀 headers는 네이티브로 지원되지 않고 샌드박스 외부 요청 변환을 통해서만 적용돼요. 그 역량이 없는 샌드박스가 제공되면 커스텀 headers를 전달할 수 없어 무시돼요.

Cursor 하네스