Vercel fx AI SDK 하네스 어댑터 분석 및 활용법

Vercel이 2026년 8월 31일 AI SDK 하네스 계층에 fx 지원을 추가했습니다. 이제 다른 코딩 하네스와 동일한 HarnessAgent 인터페이스를 통해 경량 코딩 에이전트를 실행할 수 있습니다. 다만 이 기능의 실질적인 장점은 통합 작업의 간소화에 있으며, 어떤 환경에서든 마법처럼 대체 가능한 에이전트를 제공한다는 의미는 아닙니다.

Vercel fx AI SDK 하네스 어댑터란 무엇인가

fx는 코딩 에이전트 하네스이자 명령줄 툴입니다. 하네스는 모델 호출을 둘러싼 런타임 환경으로, 모델이 실제 코딩 작업을 수행할 수 있도록 워크스페이스, 툴, 스킬, 세션, 권한, 압축(compaction), 서브에이전트 등을 관리합니다.

따라서 이는 AI SDK에 또 다른 모델 제공자를 추가하는 것과는 다릅니다. 단순히 텍스트 모델을 교체하는 것이 아니라, 애플리케이션이 이미 처리할 수 있는 인터페이스 뒤에 완성된 코딩 런타임을 추가하는 구조입니다.

새로운 @ai-sdk/harness-fx 어댑터는 HarnessAgent와 fx 사이에서 동작합니다. 내부적으로는 세션 시작, 프롬프트 전송, 진행 상황 스트리밍, 툴 처리, 정리(cleanup)를 위한 공통 언어로 Agent Client Protocol(ACP)을 사용합니다.

이제 동작 경로는 다음과 같습니다. 애플리케이션이 HarnessAgent와 통신하면, fx 어댑터가 이 요청을 ACP로 변환하고, fx는 네트워크 샌드박스 내부에서 실행되며, 모델 요청은 Vercel AI Gateway를 거쳐 전달됩니다.

핵심 원리는 단순합니다. 애플리케이션은 단일 인터페이스를 얻고, 하네스는 고유한 동작 방식을 유지합니다.

이것이 중요한 이유와 한계점

가장 크게 개선된 부분은 연동 비용입니다. 제품이 이미 HarnessAgent를 감싸고 있다면, fx를 추가하기 위해 별도의 세션 관리자, 스트림 파서, 권한 브리지, 정리 로직을 구축할 필요가 없습니다.

덕분에 플랫폼 엔지니어링 팀은 단일 제품 표면 뒤에서 여러 하네스를 깔끔하게 비교할 수 있습니다. 규모가 작은 애플리케이션 역시 별도의 오케스트레이션 스택을 유지하지 않고도 새로운 코딩 런타임을 추가할 수 있습니다.

현재 fx 사이트에는 해당 에이전트가 v0.0.7, 실험적(experimental) 단계, Apache-2.0 라이선스로 표기되어 있습니다. AI SDK 하네스 패키지 역시 실험적 상태입니다. 즉, 범위가 제한된 엔지니어링 스파이크에는 적합하지만, 안정성을 전제로 프로덕션에 즉시 도입할 만한 의존성은 아닙니다.

설치 시간, 지연 시간, 코드 생성 품질, 비용 절감 효과에 대해 공식적으로 공개된 전후 비교 데이터는 없습니다. "단일 API"라는 편리함을 근거 없는 성능 개선으로 확대 해석해서는 안 됩니다. 어댑터는 번거로운 배관 작업을 줄여줄 뿐이며, fx가 사내 레포지토리 작업을 충분히 잘 해결하는지는 직접 평가해야 합니다.

터미널에서 fx를 직접 사용하는 개발자에게는 큰 영향이 없습니다. 코딩 하네스를 실행하지 않고 일반 AI SDK 생성 함수로 모델만 호출하는 애플리케이션 역시 마찬가지입니다. 이 변화는 제품이나 사내 플랫폼에 코딩 에이전트를 내장할 때 실질적인 의미를 가집니다.

당장 활용 가능한 대상

SaaS에 레포지토리 자동 수정을 추가하는 1인 창업가

Git 레포지토리를 전달받아 에이전트가 실패한 테스트를 수정하는 앱을 운영 중이라고 가정해 보겠습니다. 기존 세션 및 스트리밍 경로를 그대로 유지한 채 일부 테스트 사용자에게 fx를 하네스로 적용할 수 있습니다. 별도의 백엔드를 가진 독자 프로토타입을 만들지 않고도 동일한 제품 내에서 실제 성능을 비교할 수 있습니다.

하네스 평가를 진행하는 에이전트 플랫폼 팀

플랫폼 팀은 fx와 다른 지원 하네스에 동일한 수정 프롬프트를 전송하고, 동일한 애플리케이션 레벨 스트림을 수집하여 작업 완료율을 비교할 수 있습니다. Claude Code, Cline, Codex, Cursor, Deep Agents, Grok Build, OpenCode, Pi 역시 하네스 계층에 포함되어 있습니다.

다만 공통 인터페이스를 사용한다고 해서 권한 동작, 툴, 압축, 내부 계획 수립 방식까지 같아지는 것은 아니므로, 하네스별 고유한 평가 기준이 여전히 필요합니다.

고객사 작업을 격리해야 하는 소프트웨어 에이전시

에이전시는 고객 레포지토리 수정 작업을 위해 단일 Vercel Sandbox를 시작하고, 진행 상황을 기존 운영 대시보드로 스트리밍한 뒤, 작업이 끝나면 세션을 삭제할 수 있습니다. 이를 통해 고객 워크스페이스를 호스트 프로세스로부터 안전하게 분리하고, 에이전트 종류에 관계없이 통일된 수명주기 패턴을 유지할 수 있습니다.

소규모 수정 작업을 처리하는 사내 개발자 도구 팀

개발자 도구 팀은 하네스 계층의 기존 스킬과 MCP 서버 구성을 유지하면서, 테스트 수정이나 간단한 기능 편집 같은 좁은 범위의 작업에 fx를 제공할 수 있습니다. 새로운 프론트엔드를 구축하지 않고도 런타임 선택지를 확장할 수 있습니다.

실습 단계

현재 fx 하네스 공식 문서는 완전한 TypeScript 구현 경로를 안내하고 있습니다. TypeScript 실행이 가능한 AI SDK 프로젝트에서 진행하십시오.

1. 1

   세 가지 패키지 설치

   하네스 코어, fx 어댑터, Vercel Sandbox 어댑터를 추가합니다.

   pnpm add @ai-sdk/harness @ai-sdk/harness-fx @ai-sdk/sandbox-vercel

2. 2

   런타임에 단일 Gateway 자격 증명 전달

   에이전트를 시작하는 런타임 환경에 VERCEL_OIDC_TOKEN 또는 AI_GATEWAY_API_KEY를 설정합니다. 둘 다 존재하는 경우 어댑터는 VERCEL_OIDC_TOKEN을 우선시합니다.

   자격 증명을 소스 코드에 직접 하드코딩하지 마십시오. 첫 번째 세션에서 fx를 다운로드하고, 이후 세션에서도 모델 호출과 웹 요청을 처리해야 하므로 샌드박스에는 네트워크 접근 권한이 필요합니다.

3. 3

   단일 세션 생성, 스트리밍, 정리

   성공 및 실패 시의 정리 로직을 포함한 공식 기본 예제입니다.

   import { HarnessAgent } from '@ai-sdk/harness/agent';
   import { fx } from '@ai-sdk/harness-fx';
   import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
   
   const agent = new HarnessAgent({
     harness: fx,
     model: 'openai/gpt-5.6-luna',
     sandbox: createVercelSandbox({
       runtime: 'node24',
       ports: [4000],
     }),
   });
   
   const session = await agent.createSession();
   
   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();
     process.exit(exitCode);
   }

4. 4

   실제 작업 전 권한 및 이벤트 테스트

   먼저 안전한 레포지토리 작업으로 테스트를 진행하십시오. 애플리케이션이 텍스트 스트림을 정상적으로 수신하는지, 권한 요청이 운영자에게 도달하는지, 작업 실패 시 session.destroy()가 정상 호출되는지 확인합니다.

   자주 간과되는 세부 사항은 외부로 노출되는 포트 설정입니다. fx는 ACP 브리지를 통해 통신하므로 네트워크 샌드박스에 최소 하나 이상의 포트가 열려 있어야 합니다. 본 예제에서는 4000 포트를 사용합니다.

다른 ACP 호환 에이전트용 어댑터를 구축해야 한다면, 관련 글인 AI SDK ACP 하네스 어댑터 분석에서 더 낮은 계층의 내용을 다루고 있으니 참고하시기 바랍니다.

비용 구조

fx 자체는 Apache-2.0 라이선스의 오픈소스이지만, 이를 내장하여 실행할 때는 모델 토큰과 Sandbox 비용이 발생합니다.

AI Gateway는 토큰에 대해 0달러의 마크업과 0달러의 플랫폼 수수료를 부과합니다. 각 Vercel 팀에는 일부 모델에 한해 낮은 분당 요청 제한이 적용되는 월 5달러 상당의 무료 크레딧이 제공됩니다. 유료 Gateway 크레딧을 구매하면 팀이 유료 플랜으로 전환되며 매월 지급되던 무료 크레딧은 종료됩니다.

샌드박스의 경우, Vercel의 iad1 리전 예시에 따르면 2 vCPU 및 4 GB 메모리 환경에서 CPU를 100% 사용할 때 5분간의 AI 코드 검증 작업 비용은 약 0.03달러입니다. 이 기준을 적용하면 모델 토큰 비용을 제외하고 1,000건의 작업당 약 30달러의 Sandbox 컴퓨팅 비용이 듭니다. 에이전트가 모델 응답이나 네트워크 I/O를 대기하는 동안의 실제 Active CPU 비용은 이보다 낮을 수 있습니다.

Pro 플랜의 Sandbox 사용량은 해당 플랜의 월 20달러 크레딧에서 먼저 차감됩니다. Sandbox의 기본 타임아웃은 5분이므로, 작업 타임아웃을 명시적으로 설정하고 완료된 세션은 방치하지 말고 즉시 정리해야 합니다.

프로덕션 도입 시 확인해야 할 5가지 제약 사항

1. 두 계층 모두 실험적 단계입니다

fx 제품과 AI SDK 하네스 패키지는 모두 실험적(experimental) 라벨이 붙어 있습니다. 하네스 공식 문서에는 릴리스 간에 호환성을 깨뜨리는 변경(breaking changes)이 발생할 수 있음이 명시되어 있습니다.

2. 어댑터가 fx의 최신 릴리스를 추적합니다

첫 세션 실행 시 fx의 공식 설치 스크립트가 실행되며, 이 스크립트는 최신 릴리스를 가져옵니다. 어댑터가 설치 경로, 실행 파일, 실행 명령어, ACP 버전을 내부적으로 고정하고 있으므로 createFx()로 이러한 세부 사항의 버전을 고정할 수 없습니다. 프로덕션 환경에서 승인된 바이너리 버전만 사용해야 하는 경우 재현성 문제가 발생할 수 있습니다.

3. 권한 모드가 정확히 일치하지 않습니다

allow-reads와 allow-edits는 모두 fx의 ask 모드로 매핑됩니다. allow-all은 code로 매핑됩니다. fx는 파일 수정은 허용하면서 터미널 명령어는 승인을 요구하는 모드를 지원하지 않으므로, 애플리케이션 레벨의 권한 이름이 의도한 대로 완벽히 반영된다고 보장할 수 없습니다.

4. ACP v1의 관측 가능성 한계

일반적인 네이티브 툴 이벤트에서 프로그래밍 방식의 툴 이름과 원시 입력값이 누락될 수 있습니다. 또한 ACP v1에는 모델 스텝 경계 및 스텝별 사용량 정보가 없어, 공통 인터페이스에서 기대하는 정밀한 트레이스 및 토큰 추적이 다소 미흡할 수 있습니다.

5. 이식할 수 없는 고급 제어 기능

이 인터페이스 경로를 통해서는 수동 세션 압축, 턴 중간 개입(mid-turn steering), 내장 툴 필터링을 표준화된 방식으로 사용할 수 없습니다. 스키마 기반 구조화된 출력(structured output) 역시 지원되지 않습니다. ACP 어댑터는 직접 어댑터에 비해 하네스의 세부 기능을 덜 노출할 수 있기 때문에, Vercel은 Claude Code와 Codex에 대해 가능한 경우 전용 직접 어댑터 사용을 권장하고 있습니다.

앞으로의 대응 방안

이미 HarnessAgent 기반 애플리케이션을 갖추고 있고, 제한된 레포지토리 작업에서 fx를 평가하고 싶으며, 실험적 패키지를 감수할 수 있다면 이번 주 바로 어댑터를 도입해 보십시오. 단일 작업 유형부터 시작하여 작업 완료율, 권한 프롬프트 발생 여부, 세션 정리 정상 작동 여부, 모델 및 Sandbox 비용을 기록해 보는 것을 추천합니다.

고정된 fx 바이너리 버전, 구조화된 출력, 스텝별 토큰 사용량, 턴 중간 개입, 또는 파일 수정과 터미널 승인의 명확한 분리가 필수적이라면 도입을 잠시 미루십시오. 이는 설정 오류가 아니라 현재 인터페이스의 구조적 한계입니다.

로컬 CLI로만 fx를 사용하거나 일반적인 모델 호출만 수행하는 애플리케이션이라면 아무런 영향을 받지 않습니다. 단지 새로운 어댑터가 출시되었다는 이유만으로 하네스 계층을 무리하게 도입할 필요는 없습니다.

실제 현업 엔지니어들이 배포에 사용하는 기술에 대한 상세한 분석을 더 확인하고 싶다면 뉴스레터를 구독해 주시기 바랍니다.