clanker25/ai

새 하네스 패키지 추가하기

이 가이드는 에이전트 하네스를 위한 새로운 @ai-sdk/harness-<name> 패키지를 생성하는 방법을 다룹니다.

런타임을 평가하기 전에 하네스 요구 사항 문서를 읽고 실현 가능성 기준과 문서화해야 할 기능 격차를 확인하세요. 하네스 패키지를 구현하는 동안 요구 사항을 따르십시오.

하네스는 호스트 기반(host-driven) 과 브리지 기반(bridge-backed) 방식이 있습니다. 호스트 기반은 런타임이 호스트 프로세스에서 실행되고 샌드박스를 원격으로 사용합니다. 브리지 기반은 런타임이 샌드박스 파일시스템이나 프로세스 환경에 로컬로 접근해야 하므로 작은 브리지가 샌드박스 내부에서 실행됩니다. 런타임이 지원하는 경우 호스트 기반을 선호하세요.

자사(First-Party) vs 타사(Third-Party) 하네스

• 타사 패키지: 모든 런타임이 외부 하네스 패키지를 게시할 수 있습니다.
• 자사 @ai-sdk/harness-<name> 패키지: 먼저 이슈를 생성하여 런타임이 이 저장소에 속하는지 논의하세요.

참고 예시

새 하네스 추가의 완전한 예시는 https://github.com/vercel/ai/pull/16255/changes 를 참조하세요.

하네스 아키텍처

AI SDK는 어댑터 패턴을 따르는 계층형 하네스 아키텍처를 사용합니다.

1. 하네스 명세 (@ai-sdk/harness): HarnessV1 및 HarnessV1Session 같은 인터페이스를 정의합니다.
2. 유틸리티 (@ai-sdk/harness/utils): 하네스 구현을 위한 공유 코드입니다.
3. 하네스 구현 (@ai-sdk/harness-<name>): 하네스에 대한 구체적인 어댑터입니다.
4. 하네스 에이전트 (@ai-sdk/harness/agent): 최종 사용자가 사용하는 고수준 HarnessAgent API입니다.

단계별 가이드

1. 패키지 구조 생성

packages/harness-<name> 디렉터리에 다음 기본 구조를 생성하세요.

packages/harness-<name>/
├── src/
│   ├── index.ts
│   ├── <name>-harness.ts
│   ├── <name>-harness.test.ts
│   └── <name>-auth.ts              # 런타임에 인증 해결이 필요한 경우
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsdown.config.ts
├── turbo.json
├── vitest.node.config.js
└── README.md

런타임이 샌드박스 내부에서 실행되어야 하는 경우 브리지 파일도 추가하세요.

src/
├── <name>-bridge-protocol.ts
├── <name>-bridge-protocol.test.ts
└── bridge/
    ├── index.ts
    ├── package.json
    └── pnpm-lock.yaml

CHANGELOG.md 파일을 패키지 제목(# @ai-sdk/harness-<name>)만 포함하여 추가하세요. 모든 패키지에는 필수로 있어야 합니다.

2. package.json 구성

기존 하네스 패키지를 스크립트, exports, 저장소 메타데이터, 게시 설정의 신뢰할 수 있는 출처로 사용하세요.

필수 패키지 기본 사항:

• "name": "@ai-sdk/harness-<name>"
• "type": "module"
• "version": "0.0.0" (새 패키지의 시작점)
• "license": "Apache-2.0"
• "sideEffects": false
• @ai-sdk/harness에 workspace:*로 의존성 추가
• 샌드박스/인증/스키마 유틸리티를 사용하는 경우 @ai-sdk/provider-utils에 workspace:*로 의존성 추가
• 하네스에 필요한 런타임 SDK/CLI 의존성
• 기존 하네스 패키지와 일치하는 devDependencies
• "engines": { "node": ">=22" }

브리지 패키지의 경우 src/bridge/ 아래 파일에 필요한 브리지 에셋 복사 단계를 추가하세요.

브리지 의존성 규칙 (브리지 기반 하네스):

• 브리지의 런타임 의존성은 메인 package.json이 아닌 src/bridge/package.json에 있습니다 (부트스트랩 시 샌드박스 내에 설치됨). 변경 후에는 pnpm --dir packages/harness-<name>/src/bridge install --lockfile-only --ignore-workspace (저장소 루트에서 실행 가능)로 src/bridge/pnpm-lock.yaml을 재생성하세요.
• src/bridge/의 모든 서드파티 임포트에 대해 src/bridge/package.json에 의존성을 추가하여 샌드박스에 설치되도록 하세요. tsdown은 메인 패키지가 선언한 dependencies, peerDependencies, optionalDependencies를 자동으로 외부화합니다. 여기에 선언되지 않은 브리지 전용 의존성은 tsdown.config.ts의 deps.neverBundle에 추가하세요. 누락된 의존성이나 필요한 제외 항목은 샌드박스 런타임에서 모듈 해석 오류로만 나타날 수 있습니다.
• 런타임이 지연(lazy) 임포트하는 패키지(예: 모델 ID에서 런타임에 해석되는 @anthropic-ai/sdk, openai 같은 프로바이더 SDK)를 src/bridge/package.json에 포함하세요. 브리지 소스에서 직접 임포트하지 않더라도 포함해야 합니다. 이러한 패키지는 해당 프로바이더 모델이 실제로 사용될 때만 실패합니다. neverBundle 항목은 브리지 소스가 임포트하지 않는 한 필요하지 않습니다.
• 공유 의존성 버전(전송, 스키마, 도구, 런타임 SDK)을 다른 하네스 패키지가 현재 사용하는 것과 일치시키세요. 자체 핀을 선택하지 말고 형제 패키지에서 복사하세요. 오래된 핀은 보안 패치와 일치하지 않아 공유 브리지 런타임과 동기화가 끊어질 수 있습니다. 생성 시점의 최신 버전을 확인하세요.

3. TypeScript, 빌드 및 테스트 설정 파일 생성

가장 가까운 기존 하네스 패키지의 설정 파일을 복사하고 경로/패키지 이름을 조정하세요.

• tsconfig.json
• tsconfig.build.json
• tsdown.config.ts
• turbo.json
• vitest.node.config.js

하네스 패키지는 다른 런타임을 추가해야 하는 특별한 이유가 없는 한 현재 Node 테스트만 사용합니다.

4. 하네스 어댑터 구현

<name>-harness.ts에서 팩토리를 내보내고 src/index.ts에서 다시 내보내세요.

계약 세부 사항은 아키텍처 문서를 참조하세요. 구현 시 다음을 확인하세요.

• specificationVersion: 'harness-v1'을 포함한 HarnessV1 반환
• 안정적인 kebab-case harnessId 사용
• builtinTools를 통해 어댑터 네이티브 내장 도구 노출
• 생성자는 동기적이며 부작용이 없도록 유지
• startOpts.sandboxSession과 startOpts.sessionWorkDir 사용. 별도의 샌드박스 생성 금지
• 지원되지 않는 런타임 기능이 필요한 메서드에서 HarnessCapabilityUnsupportedError를 throw
• 런타임이 기술적으로 기본 모델을 요구하지 않는 한 기본 모델을 하드코딩하지 마세요. 일부 기본 SDK에는 자체 기본값이 없습니다. 그렇지 않으면 소비자가 모델을 설정한 경우에만 모델을 전달하고 원래 SDK의 기본값을 그대로 둡니다. 세션의 modelId가 실제로 전송된 것과 일치하도록 유지하세요 (브리지가 자동으로 재정의한 모델을 보고하지 마세요).
• doPromptTurn/doContinueTurn이 받을 수 있는 tools와 instructions를 처리하세요. 런타임이 사용자 정의 tools를 받을 수 없으면 HarnessCapabilityUnsupportedError를 throw하여 자동으로 무시되지 않고 명확하게 알리세요. 네이티브 instructions 입력이 없으면 첫 번째 사용자 메시지 앞에 추가하세요 (Codex/Claude Code 해결 방법).
• sandbox.run/sandbox.spawn을 위한 셸 명령을 만들 때 보간된 경로(workDir, 브리지 상태 디렉터리 등)를 인용 처리하세요. 경로에 공백이 포함될 수 있습니다.

런타임이 샌드박스 내 설정이 필요한 경우 getBootstrap()을 노출하세요.

5. 런타임별 고려 사항 구현

런타임에 필요한 고려 사항만 추가하세요.

• 인증 해결 — AI Gateway 지원을 위해 환경 변수를 직접 읽지 말고 중앙의 getAiGatewayAuthFromEnv() 헬퍼를 사용하세요. 이렇게 하면 VERCEL_OIDC_TOKEN과 AI_GATEWAY_API_KEY 모두 Gateway 자격 증명으로 허용됩니다. 런타임이 프로바이더를 모델별로 해석하는 경우, 모델 ID에서 프로바이더를 해석하고 해당 프로바이더의 환경 변수를 설정하세요. 게이트웨이를 통해 라우팅하는 경우 기본 URL 규칙이 프로바이더마다 다르다는 점에 유의하세요 (예: Anthropic 클라이언트는 루트 기본 URL에 /v1/messages를 추가하고, OpenAI 클라이언트는 /v1 기본 URL에 추가합니다).
• AI Gateway 클라이언트 속성 — 기존 하네스 패키지의 규칙을 따르세요. ai-sdk/harness-<name>/${VERSION} 같은 버전이 지정된 클라이언트 앱 값을 정의하고 Gateway 요청에 사용하세요. 기본 런타임/SDK가 둘 다 지원하는 경우 User-Agent와 x-client-app 헤더를 모두 구성하세요. 이 두 헤더 중 하나는 필수입니다. 런타임이 임의의 헤더를 직접 설정할 수 없는 경우, 해당 헤더 중 하나를 생성하는 런타임 지원 방식을 사용하세요 (예: SDK 클라이언트 앱 환경 변수).
• 사용자 정의 도구 스키마 변환 — 호스트 도구의 JSON Schema를 런타임 도구 형식으로 변환하는 경우 재귀적으로 변환하세요 (중첩 객체, 배열 items, enums, 설명). 평면적인 최상위 수준 변환만 수행하면 모델의 구조화된 지침이 자동으로 삭제됩니다. 런타임이 허용하는 경우 JSON Schema를 직접 전달하면 이 문제를 피할 수 있습니다.
• 스킬 또는 발견 파일(discovery-file) 구체화(materialization)
• 네이티브 프로토콜을 하네스 스트림/제어로 변환
• 생명 주기 상태 스키마
• 브리지 프로토콜 및 진단

하네스 어댑터의 특정 구조적 규칙은 konsistent CLI를 통해 적용됩니다. 완료되면 pnpm konsistent을 실행하여 확인하세요. 진행하기 전에 발견된 위반 사항을 수정하세요.

6. 테스트 작성

다음에 대한 집중적인 Node 테스트를 추가하세요.

• 팩토리 메타데이터 및 설정
• 인증 해결
• 샌드박스 사용 및 경로 배치
• 호스트 기반 원격 작업 또는 브리지 프로토콜 동작
• 프롬프트/제어 이벤트 변환
• 세션 재개 대 연속 턴(turn) 동작
• 지원되지 않는 기능 오류
• 스킬 구체화(지원되는 경우)

가능한 경우 모의(mocked) 샌드박스 세션과 브리지/런타임 경계를 사용하세요. 단위 테스트에서 라이브 프로바이더 자격 증명이 필요하지 않도록 하세요.

getBootstrap()은 컴파일된 브리지 에셋(예: dist/bridge/index.mjs)을 읽습니다. 이 파일은 src에 대해 테스트를 실행할 때 존재하지 않으므로 호출 시 ENOENT 오류가 발생합니다. 브리지 에셋 경로에 대해 node:fs/promises의 readFile을 모의 처리하세요 (Codex/OpenCode 하네스 테스트에서 패턴을 참조).

7. README 추가

README를 간결하게 유지하세요.

• 패키지 목적
• 설정 명령
• 최소 HarnessAgent 사용 예시
• 필수 샌드박스 기능 (예: 브리지 기반 런타임의 포트)
• 중요한 인증 설정

광범위한 개념에 대한 주요 하네스 문서로 링크하세요.

8. 예제 추가

새 하네스에 대한 관련 예제를 추가하세요.

• examples/ai-functions/src/harness-agent 아래에 필수 API/함수 예제를 추가하고 examples/harness-e2e-next 아래에 대화형 예제를 추가하세요.

9. 문서화

content/providers/02-ai-sdk-harnesses/<next number>-<name>.mdx에 문서를 만드세요.

다음을 포함하세요.

• 설정 지침
• 필수 샌드박스 기능
• 인증 구성
• 하네스별 옵션
• 사용 예제
• 알려진 제한 사항

공개할 준비가 되면 content/docs/03-ai-sdk-harnesses/05-harness-adapters.mdx를 업데이트하여 새 하네스를 나열하세요.

10. 참조 업데이트 및 검증

워크스페이스 루트에서 다음을 실행하세요.

pnpm konsistent
pnpm update-references
pnpm --filter @ai-sdk/harness-<name> build
pnpm --filter @ai-sdk/harness-<name> test
pnpm type-check:full

pnpm changeset으로 체인지셋을 추가하세요. 완전히 새로운 하네스 패키지의 첫 번째 릴리스의 경우 major를 사용하세요 (일반적인 patch가 아닙니다). 다른 하네스 패키지와 일치시킵니다.

라이브 샌드박스에 대해 관련 하네스 예제를 일찍 실행하세요. 단위 테스트와 type-check에만 의존하지 마세요. 런타임 API 제약 조건(예: 예상치 못한 구성 옵션 거부, 런타임이 내보내는 정확한 스트리밍 이벤트 이름, 게이트웨이 기본 URL 형식)은 브리지가 실제로 런타임을 구동할 때만 표시되며, 문서/예제가 그 위에 구축되기 전에 발견하는 것이 훨씬 저렴합니다.

체크리스트

• packages/harness-<name>에 패키지 구조 생성
• 올바른 의존성으로 package.json 구성
• TypeScript 설정 완료 (tsconfig.json, tsconfig.build.json)
• 빌드 설정 (tsdown.config.ts)
• 테스트 설정 (vitest.node.config.js)
• 하네스 어댑터 구현 완료
• 숨겨진 샌드박스를 생성하지 않고 런타임 배치 처리
• 브리지 기반인 경우 빌드 중 브리지 에셋 복사
• 필요한 경우 인증 해결 구현
• AI Gateway 요청에 User-Agent 및/또는 x-client-app 클라이언트 속성 포함
• 하네스 인프라, 스킬, 브리지 코드, 비밀 정보를 sessionWorkDir 외부에 유지
• 세션 재개 및 턴 연속 테스트
• 단위 테스트 작성 및 통과
• README.md 작성
• CHANGELOG.md 추가 (패키지 제목, konsistent에서 요구)
• 체인지셋 추가 (첫 번째 릴리스의 경우 major)
• 예제 추가
• content/providers/02-ai-sdk-harnesses/에 문서 추가
• 공개인 경우 하네스 어댑터 목록 업데이트
• 라이브 샌드박스에 대해 검증 완료 (단위 테스트 / type-check 만으로는 불충분)
• pnpm update-references 실행
• 패키지 빌드 통과
• 패키지 테스트 통과
• 타입 검사 통과 (루트에서 pnpm type-check:full)
• 관련 예제가 성공적으로 실행됨

관련 문서

• 하네스 추상화 아키텍처
• @ai-sdk/harness README
• 유사한 런타임 배치를 가진 기존 하네스 패키지