OpenCode Harness

OpenCode harness 어댑터는 @opencode-ai/sdk를 통해 HarnessAgent를 OpenCode에 연결해요. 어댑터는 샌드박스 내부에서 브리지를 실행하고, 그 샌드박스에서 OpenCode 서버를 시작한 후, 샌드박스로 노출된 WebSocket을 통해 OpenCode 세션 이벤트를 호스트로 스트리밍해요.

Harness 패키지는 실험적이에요. 이 초기 API가 더 정제됨에 따라 릴리스 간에 breaking change가 있을 수 있으니 주의하세요.

출처: 문서

본문

설정

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

첫 번째 세션이 시작될 때 어댑터가 샌드박스 내부의 OpenCode 브리지 의존성을 부트스트랩해요. 브리지 패키지는 @opencode-ai/sdk와 opencode-ai에 의존해요.

임포트

import { openCode, createOpenCode } from '@ai-sdk/harness-opencode';

openCode은 기본 설정을 사용한 createOpenCode()와 동일해요.

기본 사용법

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

const agent = new HarnessAgent({
  harness: openCode,
  model: 'anthropic/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과, OpenCode용 인증에 나열된 변수 중 하나가 포함되어 있어야 해요.

어댑터 설정

createOpenCode()를 사용해 런타임을 구성해요:

const harness = createOpenCode({
  reasoningVariant: 'high',
  openCodeConfig: {
    agent: {
      general: {
        model: 'openai/gpt-5.4-mini',
      },
    },
  },
});

설정 항목:

auth: 인증 모드(auto, anthropic, openai, 또는 ai-gateway) 또는 격리된 인증 환경.
credentialForwarding: harness 어댑터가 자격 증명을 샌드박스 프로세스로 전달하기 직전에 각 자격 증명을 커스텀하는 선택적 동기/비동기 콜백. 실제 자격 증명 또는 마스킹된 값을 전달하고 이를 노출하는 데 사용되는 환경 변수 이름을 받아요. 이 콜백은 샌드박스 프로세스로 전달되는 값만 제어해요. 호스트 프로세스에서 harness 어댑터가 자격 증명을 발견, 읽기 또는 접근하는 것을 제한하지 않아요.
mcpServers: 서버 이름별 MCP 서버 정의.
openCodeConfig: 추가 네이티브 OpenCode 설정. 어댑터 관리 설정이 우선해요. 에이전트 로컬 permission과 더 이상 사용되지 않는 tools 설정은 무시되어 harness 권한이나 내장 도구 필터링을 우회할 수 없어요.
provider: HarnessAgent의 model에 접두사가 없을 때 사용할 프로바이더 id.
reasoningVariant: 지원되는 모델에 대한 OpenCode reasoning/thinking 변형, 예: low, medium, high.
port: 브리지 포트 재정의.
startupTimeoutMs: 브리지가 시작될 때까지 대기하는 최대 시간.
reconnect: 설정된 브리지 WebSocket 연결이 끊긴 후의 재연결 타이밍. maxElapsedMs는 연결 설정과 백오프 지연을 포함한 전체 재시도 창을 제어하며 기본값은 30초. initialDelayMs는 기본값 50밀리초, maxDelayMs는 기본값 2초. 이 재시도는 지수 백오프를 사용하며 startupTimeoutMs와 별개예요. 샌드박스, 브리지 프로세스 또는 브리지 엔드포인트가 영구적으로 사용 불가한 경우에는 복구할 수 없어요.
mintBridgeToken: 샌드박스 id를 받고 브리지 인증 토큰을 반환하는 동기 함수. 기본적으로 어댑터는 무작위 32바이트 토큰을 생성해요. 커스텀 구현은 적절히 비밀스러운 토큰을 반환해야 해요.

구조화된 출력

OpenCode는 스키마 기반 HarnessAgent 구조화된 출력을 지원해요. 어댑터는 OpenCode의 json_schema 프롬프트 형식을 사용하고 검증된 structured 결과를 JSON 텍스트로 반환해요.

인증

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

auto(기본값): 사용 가능하면 AI Gateway 자격 증명을 사용한 다음 선택된 모델 프로바이더의 자격 증명을 사용해요.
anthropic: Anthropic 자격 증명 사용.
openai: OpenAI 자격 증명 사용.
ai-gateway: AI Gateway 자격 증명 사용.

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

지원되는 환경 변수:

AI_GATEWAY_API_KEY
AI_GATEWAY_BASE_URL
VERCEL_OIDC_TOKEN
ANTHROPIC_API_KEY
ANTHROPIC_AUTH_TOKEN
ANTHROPIC_BASE_URL
OPENAI_API_KEY
OPENAI_BASE_URL
OPENAI_ORGANIZATION
OPENAI_PROJECT

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

자동 감지를 원하지 않으면 특정 인증 모드를 선택해요:

const anthropicHarness = createOpenCode({ auth: 'anthropic' });
const openAIHarness = createOpenCode({ auth: 'openai' });
const gatewayHarness = createOpenCode({ auth: 'ai-gateway' });

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

const harness = createOpenCode({
  auth: { OPENAI_API_KEY: await resolveOpenAIToken() },
  provider: 'openai',
});

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

OpenAI 호환 엔드포인트의 경우 openai를 선택하고 OPENAI_BASE_URL을 설정해요.

샌드박스

OpenCode는 노출된 포트가 하나 이상 있는 네트워크 샌드박스가 필요해요, 예: @ai-sdk/sandbox-vercel:

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

내장 도구

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

read
write
edit
bash
glob
grep
ls
webfetch
skill
todowrite
agent

일반적인 도구 형태에 맞지 않으면 추가 OpenCode 내장 기능이 agent.tools에 나타날 수도 있어요.

permissionMode가 allow-reads 또는 allow-edits일 때 OpenCode는 내장 도구 승인 요청을 지원해요. 호스트에서 실행되는 AI SDK 도구 승인도 작동해요.

더 알아보기 (Learn more)

출처 문서: OpenCode Harness

OpenCode Harness