Claude Code Harness

Claude Code harness 어댑터는 HarnessAgent 를 @anthropic-ai/claude-agent-sdk 를 통해 Claude Code에 연결해요. 이 어댑터는 sandbox 안에서 브리지를 실행하고 sandbox에 노출된 WebSocket을 통해 Claude Code 이벤트를 호스트로 다시 스트리밍해요.

Harness 패키지는 **실험적**이에요. 이 초기 API가 더 다듬어지면서 릴리스 사이에 호환성이 깨지는 변경이 있을 수 있어요.

출처: 문서

본문

설정 (Setup)

어댑터는 첫 번째 세션이 시작될 때 sandbox 안에서 Claude Code 브리지 의존성을 부트스트랩해요.

Import

import { claudeCode, createClaudeCode } from '@ai-sdk/harness-claude-code';

claudeCode 는 기본 설정을 가진 createClaudeCode() 와 동일해요.

기본 사용법

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

const agent = new HarnessAgent({
  harness: claudeCode,
  model: 'claude-sonnet-4-6',
});

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 과, Claude Code용으로 인증 섹션에 나열된 변수 중 하나가 포함되어야 해요.

어댑터 설정

createClaudeCode() 를 사용해 런타임을 설정하세요:

const harness = createClaudeCode({
  maxTurns: 10,
  env: {
    DEPLOYMENT_ENV: 'staging',
  },
  thinking: {
    type: 'adaptive',
    display: 'summarized',
  },
});

설정:

auth: 인증 모드(auto, direct, ai-gateway) 또는 격리된 인증 환경.
credentialForwarding: harness 어댑터가 자격 증명을 sandbox 프로세스로 전달하기 직전에 각 자격 증명을 사용자 정의하는 선택적 동기/비동기 콜백. 전달될 자격 증명 값(실제 자격 증명 또는 마스킹된 값)과 이를 노출하는 데 사용되는 환경 변수 이름을 받아요. 이 콜백은 sandbox 프로세스로 전달되는 값만 제어해요. harness 어댑터가 호스트 프로세스에서 발견/읽기/접근할 수 있는 자격 증명을 제한하지는 않아요.
mcpServers: 서버 이름 키로 된 MCP 서버 정의.
maxTurns: 제어를 양보하기 전 최대 내부 턴 수.
env: Claude Code 프로세스를 위한 환경 변수. 값들은 sandbox 브리지 프로세스 환경 위에 병합되며 우선해요.
thinking: 확장 사고(extended-thinking) 설정. type 은 enabled, disabled, adaptive 일 수 있어요. enabled 또는 adaptive 사고의 경우 display 는 summarized 또는 omitted 일 수 있어요. 기본값은 { type: 'adaptive', display: 'summarized' }.
port: 브리지 포트 오버라이드.
startupTimeoutMs: 브리지가 시작될 때까지 기다리는 최대 시간.
reconnect: 설정된 브리지 WebSocket 연결이 끊긴 후 재연결 타이밍. maxElapsedMs 는 연결 설정과 백오프 지연을 포함한 총 재시도 창을 제어하며 기본값은 30초. initialDelayMs 는 기본 50밀리초, maxDelayMs 는 기본 2초. 이 재시도는 지수 백오프를 사용하며 startupTimeoutMs 와는 별개예요. sandbox, 브리지 프로세스, 또는 브리지 엔드포인트가 영구적으로 사용 불가하면 복구할 수 없어요.
mintBridgeToken: sandbox ID를 받아 브리지 인증 토큰을 반환하는 동기 함수. 기본적으로 어댑터는 무작위 32바이트 토큰을 생성해요. 커스텀 구현은 적절히 비밀인 토큰을 반환해야 해요.

구조화된 출력 (Structured Output)

Claude Code는 스키마 기반 HarnessAgent 구조화된 출력 을 지원해요. 어댑터는 Agent SDK의 네이티브 outputFormat 옵션을 통해 JSON Schema를 전달하고 그 structured_output 값을 JSON 텍스트로 반환해요.

인증 (Authentication)

auth 설정은 호스트 환경에서 자격 증명을 어떻게 해석하는지 선택해요:

auto (기본값): 사용 가능하면 AI Gateway 자격 증명을 사용하고, 그다음 직접 Anthropic 자격 증명으로 폴백.
direct: Anthropic 자격 증명 사용.
ai-gateway: AI Gateway 자격 증명 사용.

sandbox가 덧셈 요청 변환(additive request transformations)을 지원하면 브리지는 자리표시자를 받고 어댑터는 일치하는 아웃바운드 요청에 자격 증명을 주입해요. 그 기능이 없는 sandbox는 직접 자격 증명 전달을 유지해요.

지원되는 환경 변수:

VERCEL_OIDC_TOKEN
AI_GATEWAY_API_KEY
AI_GATEWAY_BASE_URL
ANTHROPIC_API_KEY
ANTHROPIC_AUTH_TOKEN
ANTHROPIC_BASE_URL

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

자동 감지가 싫을 때 특정 인증 모드를 선택하세요:

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

process.env 를 읽지 않고 프로그래밍 방식으로 해석된 자격 증명을 사용하려면 인증 환경을 전달하세요:

const harness = createClaudeCode({
  auth: { ANTHROPIC_API_KEY: await resolveAnthropicToken() },
});

제공된 레코드는 인증 발견을 위해 호스트 환경을 대체해요. 인식된 인증 변수만 전달돼요.

Sandbox

Claude Code는 노출된 포트가 하나 이상 있는 네트워크 sandbox를 필요로 해요. 예: @ai-sdk/sandbox-vercel:

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

내장 Tool (Built-in Tools)

어댑터는 agent.tools 를 통해 다음 일반 Claude Code 내장 기능을 노출해요:

read
write
edit
bash
glob
grep
webSearch

다른 Claude Code 내장 기능이 일반 tool 형태에 맞지 않으면 agent.tools 에도 나타날 수 있어요.

Claude Code는 permissionMode 가 allow-reads 또는 allow-edits 일 때 내장 tool 승인 요청을 지원해요.

더 알아보기 (Learn more)

전체 사이트맵

Claude Code Harness