Grok Build 하네스

Grok Build 하네스 (Grok Build Harness)

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

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

출처: 문서

본문

셋업 (Setup)

npm install @ai-sdk/harness @ai-sdk/harness-grok-build @ai-sdk/sandbox-vercel

ACP 하네스는 첫 세션이 시작될 때 샌드박스 안에 고정된 Grok Build CLI를 설치해요.

Import

import { createGrokBuild, grokBuild } from '@ai-sdk/harness-grok-build';

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

기본 사용법 (Basic Usage)

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

const agent = new HarnessAgent({
  harness: grokBuild,
  model: 'grok-build-0.1',
});

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과 Grok Build용으로 authentication 아래 나열된 변수 중 하나가 포함돼 있는지 확인하세요.

어댑터 설정 (Adapter Settings)

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

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

설정:

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

어댑터는 Grok Build CLI와 ACP 런치 명령을 고정해요. 이 구현 세부사항은 createGrokBuild()로 재정의할 수 없어요.

구조화 출력 (Structured Output)

Grok Build는 스키마 기반 HarnessAgent 구조화 출력을 지원해요. 그 프로파일은 JSON Schema를 Grok Build의 프라이빗 ACP 프롬프트 메타데이터로 매핑하고, 런타임이 provider 구조화 출력 메커니즘을 통해 이를 강제해요.

인증 (Authentication)

기본적으로 인증은 호스트 환경에서 해결돼요. 샌드박스가 가산적 요청 변환을 지원하면 Grok Build는 플레이스홀더를 받고 어댑터가 일치하는 아웃바운드 요청에 자격 증명을 주입해요. 다른 샌드박스는 직접 자격 증명 전달을 유지해요.

지원 환경 변수:

• VERCEL_OIDC_TOKEN
• AI_GATEWAY_API_KEY
• AI_GATEWAY_BASE_URL
• XAI_API_KEY

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

직접 인증을 사용하면 어댑터는 XAI_API_KEY를 사용해요. AI Gateway를 사용하면 Gateway 자격 증명을 XAI_API_KEY로 공급하고, /v1로 끝나는 Gateway base URL을 GROK_XAI_API_BASE_URL과 GROK_MODELS_BASE_URL로 매핑하며, 클라이언트 귀속을 위해 GROK_CLIENT_NAME과 GROK_CLIENT_VERSION을 설정해요.

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

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

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

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

제공된 record는 인증 발견을 위해 호스트 환경을 대체하므로 XAI_API_KEY로 직접 인증을 선택할 수도 있어요.

샌드박스 (Sandbox)

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

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

첫 세션은 ACP 하네스가 샌드박스 안에 @xai-official/[email protected]를 설치할 수 있도록 네트워크 이그레스(egress)가 필요해요.

내장 도구 (Built-in Tools)

어댑터는 다음 Grok Build 내장 도구를 공통 하네스 도구로 매핑해요:

• bash (run_terminal_command)
• edit (search_replace)
• grep
• webSearch (web_search)
• write

다른 Grok Build 도구는 네이티브 이름으로 계속 사용할 수 있어요. read_file, list_dir, todo_write, spawn_subagent, monitor, 워크플로·스케줄러 도구, 이미지 생성 도구가 포함돼요.

Grok Build는 권한 동작에 대해 ACP 세션 모드를 알리지 않아요. Grok이 ACP 권한 요청을 보내면 ACP 하네스는 도구 종류에 따라 구성된 Harness permissionMode를 적용해요. Grok은 안전한 내장 연산을 권한 요청을 보내지 않고 내부적으로 처리할 수 있어요.

알려진 제한 (Known Limitations)

• ACP v1은 모델 스텝 경계나 스텝별 사용량을 노출하지 않아요. 어댑터는 경계를 추론하고 Grok이 합계를 제공하지 않을 때 알 수 없는 스텝별 사용량을 보고해요.
• ACP v1에는 휴대 가능한 수동 압축 또는 미드 턴 스티어링 API가 없어요.
• ACP v1에는 휴대 가능한 내장 도구 필터링 API가 없어요. 호스트 도구 필터링은 지원되지만 Grok 내장 도구를 필터링하면 지원되지 않는 역량 오류가 throw돼요.
• Grok Build는 현재 내장 도구 승인 요청을 지원하지 않아요. 이 어댑터로 permissionMode: 'allow-all'를 사용하세요. 호스트 실행 AI SDK 도구 승인은 여전히 작동해요.
• 변경된 호스트 도구 카탈로그는 Grok Build가 ACP MCP 도구 목록을 새로고쳐야 해요. 구현이 오래된 도구를 유지하면 턴이 명시적으로 실패해요.
• 커스텀 headers는 네이티브로 지원되지 않고 샌드박스 외부 요청 변환을 통해서만 적용돼요. 그 역량이 없는 샌드박스가 제공되면 커스텀 headers를 전달할 수 없어 무시돼요.

더 알아보기 (Learn more)

• HarnessAgent
• Harness 도구
• Harness 어댑터
• Agent Client Protocol