무엇이 달라졌나

Vercel은 AI SDK 7에 HarnessAgent라는 통합 API를 도입했다. 이 API의 목적은 Claude Code, Codex, Pi처럼 이미 존재하는 에이전트 하네스를 동일한 애플리케이션 흐름에서 실행하도록 만드는 것이다. 이전 AI SDK가 모델을 교체해도 에이전트 코드를 크게 다시 작성하지 않는 방향에 초점을 맞췄다면, 이번 변화는 그 추상화 범위를 모델 위에서 동작하는 하네스까지 넓힌다.

여기서 하네스는 단순히 언어 모델을 호출하는 얇은 래퍼가 아니다. 스킬, 샌드박스, 세션, 권한 승인 흐름, 대화 압축, 런타임 설정, 하위 에이전트 같은 실행 요소를 관리한다. 같은 모델을 사용하더라도 어떤 하네스를 선택하느냐에 따라 파일 접근 방식, 명령 실행 과정, 컨텍스트 관리, 승인 절차가 달라질 수 있다. 따라서 HarnessAgent의 핵심 가치는 여러 제품의 모든 기능을 같게 만드는 데 있지 않고, 애플리케이션이 하네스에 접근하는 공통 진입점을 제공하는 데 있다.

초기 실험 버전에는 Claude Code, Codex, Pi용 어댑터가 포함된다. 개발자는 HarnessAgent를 중심으로 세션 생성, 프롬프트 전달, 결과 스트리밍, 세션 종료 흐름을 작성한 뒤 하네스 설정을 교체할 수 있다. 다만 각 하네스의 고유 기능과 동작까지 완전히 동일해진다고 해석해서는 안 된다. 실제 전환 전에는 필요한 도구 호출, 스킬, 권한 흐름과 이벤트가 선택한 어댑터에서 어떻게 지원되는지 확인해야 한다.

코드 구조에서 확인할 변화

공개된 예시는 HarnessAgent에 Claude Code 어댑터와 Vercel Sandbox를 연결하고, 필요한 도구와 스킬을 전달하는 구조다. 샌드박스에는 Node.js 24 런타임과 포트 설정이 지정되어 있다. 이후 세션을 만들고, 테스트 실패를 조사해 제품 코드를 수정하라는 작업을 스트리밍 방식으로 요청한 다음, 반환되는 텍스트 조각을 순서대로 처리한다. 작업이 성공하거나 중간에 오류가 발생하더라도 마지막에는 세션을 제거한다.

이 예제에서 실무적으로 중요한 부분은 특정 프롬프트보다 세션 생명주기다. 세션을 언제 생성하고 재사용할지, 실패한 작업을 다시 실행할 때 기존 상태를 이어갈지, 완료 후 어떤 자원을 정리할지를 애플리케이션 코드가 명확히 결정해야 한다. 특히 자동화 서버나 CI에서 세션 종료가 누락되면 실행 자원과 임시 데이터가 예상보다 오래 남을 가능성을 검토해야 한다.

Claude Code 어댑터를 Codex나 Pi 어댑터로 바꾸더라도 HarnessAgent의 기본 흐름은 유지할 수 있다는 것이 Vercel의 설명이다. 또한 HarnessAgent의 generate와 stream 결과는 AI SDK 형식과 호환되도록 제공된다. 이미 useChat 또는 관련 AI SDK 도구를 사용하는 애플리케이션이라면 사용자 인터페이스 코드를 바꾸지 않고 에이전트 실행 계층을 교체할 가능성이 있다. 그러나 서버에서 보내는 이벤트의 종류, 오류 처리 방식, 중간 도구 결과를 UI가 어떻게 표현하는지는 별도로 테스트하는 편이 안전하다.

모델 추상화와 하네스 추상화의 차이

모델 교체는 주로 입력 메시지와 생성 결과, 토큰 사용량, 도구 호출 형식을 맞추는 문제다. 하네스 교체는 그보다 넓은 실행 환경을 다룬다. 에이전트가 저장소를 읽고 파일을 수정하며 명령을 실행한다면, 결과 품질뿐 아니라 권한 경계와 작업 공간 상태도 달라질 수 있다.

  • 모델 계층: 응답 품질, 지연 시간, 컨텍스트 한도, 도구 호출 능력 등을 비교한다.
  • 하네스 계층: 세션 유지, 파일 접근, 명령 실행, 승인 절차, 스킬 로딩, 컨텍스트 압축과 하위 에이전트 운영을 비교한다.
  • 애플리케이션 계층: 사용자 인증, 작업 요청, 결과 표시, 감사 기록, 실패 복구와 비용 통제를 담당한다.

통합 API가 생겨도 이 세 계층의 책임이 사라지는 것은 아니다. 오히려 하네스를 쉽게 교체할 수 있게 되면 어떤 차이를 애플리케이션이 보정해야 하는지 명시하는 일이 중요해진다. 동일한 프롬프트와 저장소를 사용해도 수정 범위, 명령 실행 횟수, 승인 요청 시점, 세션에 남는 정보가 다를 수 있기 때문이다.

누가 먼저 검토할 만한가

여러 코딩 에이전트를 비교하는 개발자

개인 프로젝트나 실험 환경에서 Claude Code, Codex, Pi를 번갈아 평가한다면 공통 실행 코드를 유지할 수 있다는 점이 유용하다. 단순한 대화 품질보다 저장소 탐색, 테스트 실행, 패치 생성, 실패 복구처럼 실제 작업 단위를 같은 조건에서 비교하기 쉬워진다. 다만 어댑터 이름만 교체한 결과를 공정한 비교로 단정하지 말고, 각 하네스에 제공한 권한과 스킬, 런타임이 같은지도 기록해야 한다.

AI 기능을 제품에 넣는 개발팀

이미 AI SDK의 스트리밍 결과나 useChat 기반 UI를 사용하는 팀이라면 프런트엔드를 유지하면서 서버의 실행 하네스를 바꿀 수 있는지 검토할 가치가 있다. 이 경우 핵심 질문은 화면 수정량이 아니라 인증, 세션 격리, 취소 요청, 오류 이벤트, 도구 실행 상태가 기존 계약과 호환되는지다. 사용자가 브라우저를 닫거나 생성을 취소했을 때 서버 세션과 샌드박스도 정리되는지 확인해야 한다.

CI/CD와 개발 자동화를 운영하는 팀

테스트 실패 조사, 정적 분석 결과 정리, 제한된 코드 수정처럼 반복적이고 검증 가능한 작업부터 적용할 수 있다. 에이전트가 변경한 내용을 바로 배포하는 구성은 피하고, 패치 검토와 테스트 통과를 별도의 승인 단계로 두는 것이 좋다. 하네스를 바꾸더라도 동일한 브랜치 보호 규칙, 비밀정보 차단, 명령 허용 목록과 감사 로그가 유지되어야 한다.

학생과 연구자

여러 에이전트의 행동을 비교하는 실험에서는 공통 API가 실험 코드를 단순화할 수 있다. 그러나 재현성을 확보하려면 하네스 이름만으로는 부족하다. 사용한 패키지 버전, 모델, 프롬프트, 샌드박스 런타임, 도구와 스킬, 권한 설정, 세션 재사용 여부를 함께 남겨야 한다. 이번 기능은 실험 단계이므로 같은 코드가 향후 버전에서 그대로 동작한다고 가정해서도 안 된다.

샌드박스를 어떻게 해석해야 하나

Vercel은 각 하네스가 샌드박스 작업 공간에서 실행되어 호스트 환경과 분리된다고 설명한다. 이는 로컬 머신이나 애플리케이션 서버에서 에이전트 명령을 직접 실행하는 것보다 분명한 설계상 이점이다. 하지만 “샌드박스에서 실행된다”는 설명만으로 모든 보안 검토를 끝낼 수는 없다.

  • 저장소 전체가 전달되는지, 선택한 디렉터리나 파일만 마운트할 수 있는지 확인한다.
  • 환경 변수와 배포 키, 패키지 레지스트리 토큰이 어떤 조건에서 노출되는지 확인한다.
  • 외부 네트워크 연결의 기본값과 허용 가능한 목적지를 확인한다.
  • 열린 포트가 외부에 공개되는지, 세션 내부에서만 접근되는지 확인한다.
  • 세션 종료 후 파일, 로그, 명령 출력이 언제 제거되는지 공식 문서와 계약 조건에서 확인한다.
  • 하위 에이전트가 부모와 같은 권한을 상속하는지, 별도의 제한을 둘 수 있는지 확인한다.

업무 코드, 미공개 연구 자료, 개인정보가 포함된 데이터를 사용한다면 샌드박스의 기술적 격리와 서비스의 데이터 보존 정책을 따로 검토해야 한다. 원문에는 구체적인 보존 기간이나 데이터 처리 조건이 제시되어 있지 않으므로, 실제 적용 시점의 공식 문서와 조직 계약을 기준으로 판단해야 한다.

가격과 운영 비용을 판단하는 기준

원문은 HarnessAgent의 별도 가격, 샌드박스 사용료, 각 하네스나 모델의 과금 관계를 설명하지 않는다. 따라서 통합 API가 생겼다는 사실만으로 비용이 낮아진다고 판단할 수 없다. 최소한 모델 사용량, 샌드박스 실행 시간, 세션 수, 네트워크와 저장 공간, 외부 도구 호출 비용을 구분해 측정해야 한다.

하네스 교체가 쉬워져도 과금 단위가 서로 같아지는 것은 아니다. 비교 테스트에서는 작업 완료 한 건을 기준으로 총 실행 시간, 재시도 횟수, 사람이 수정한 횟수, 생성된 변경량을 함께 기록하는 편이 유용하다. 호출당 단가가 낮더라도 실패와 재시도가 많다면 실제 작업 비용은 커질 수 있다. 반대로 비용이 다소 높더라도 검토 시간을 꾸준히 줄인다면 반복 업무에서 가치를 만들 수 있다.

도입 전 작은 검증 절차

  1. 한 가지 작업을 고른다. 실패한 단위 테스트 한 개 수정, 작은 문서 갱신, 제한된 리팩터링처럼 성공 조건이 분명한 작업이 적합하다.
  2. 고정된 입력을 준비한다. 같은 저장소 상태와 프롬프트, 런타임, 도구 권한을 사용해야 하네스 차이를 비교할 수 있다.
  3. 최소 권한으로 실행한다. 읽기 전용으로 시작한 뒤 파일 수정과 명령 실행 권한을 필요한 범위에서만 추가한다.
  4. 세션 종료를 검증한다. 정상 완료, 오류, 사용자 취소 각각에서 세션과 샌드박스가 정리되는지 확인한다.
  5. 결과뿐 아니라 과정을 기록한다. 실행 명령, 수정 파일, 승인 요청, 실패 이유, 재시도 횟수와 사람이 개입한 시간을 남긴다.
  6. 롤백 경로를 만든다. 생성된 변경은 별도 브랜치나 격리된 작업 공간에 두고 기존 실행 경로로 즉시 돌아갈 수 있어야 한다.
  7. 여러 하네스로 반복한다. 공통 API가 실제로 유지되는 범위와 하네스별 예외 처리가 필요한 지점을 찾는다.

현재 단계에서 주의할 제한

HarnessAgent는 AI SDK의 canary 배포판에서 제공되며, 관련 하네스 패키지도 실험적 상태다. Vercel은 API가 다듬어지는 동안 릴리스 사이에 호환성을 깨는 변경이 발생할 수 있다고 안내한다. 따라서 안정 버전과 동일한 수준의 호환성을 기대해 제품 핵심 경로에 즉시 고정하는 것은 위험할 수 있다.

검토 중이라면 정확한 패키지 버전을 잠그고, 업그레이드 시 변경 기록과 타입 오류를 확인하며, 통합 테스트를 통과한 뒤 배포해야 한다. 실험 API를 사용하는 모듈을 애플리케이션 전체에 직접 퍼뜨리지 않고 내부 어댑터 뒤에 두면 향후 API 변경이나 다른 실행 방식으로의 복귀가 쉬워진다. 프로덕션 적용 여부는 기능 소개보다 장애 시 영향 범위, 이전 버전으로 돌아가는 시간, 공식 지원 범위를 기준으로 결정하는 편이 합리적이다.

선택 기준

  • 도입 가치가 큰 경우: 둘 이상의 하네스를 실제로 운영하거나 비교해야 하고, 현재 하네스별 통합 코드가 중복되어 있으며, AI SDK 기반 UI와 스트리밍 흐름을 이미 사용하고 있다.
  • 작게 시험할 경우: 한 하네스만 사용하지만 향후 교체 가능성이 있고, 격리된 코드 작업이나 반복적인 CI 업무를 자동화하려 한다.
  • 기다리는 편이 나은 경우: 안정적인 API가 필수이거나, 현재 하네스 통합이 단순하고, 실험 패키지의 변경을 따라갈 유지보수 여력이 없다.
  • 적용을 보류할 경우: 데이터 보존, 네트워크 접근, 비밀정보 처리, 비용 상한을 확인하지 못했거나 세션 실패 시 정리와 롤백 절차가 마련되지 않았다.

결국 이번 변화의 의미는 특정 코딩 에이전트가 더 우수하다는 선언이 아니다. 애플리케이션 코드를 하나의 하네스 구현에 강하게 묶지 않고, 작업 성격과 운영 조건에 맞는 실행 계층을 선택할 수 있는 기반을 제안했다는 데 있다. 실제 가치는 작은 동일 작업을 여러 하네스로 실행해 품질, 권한, 실패 복구, 비용을 함께 비교했을 때 확인할 수 있다.

출처와 검증

기능 범위, 지원 어댑터, canary 제공 상태와 실험 패키지 관련 내용은 Vercel의 2026년 6월 12일 발표를 기준으로 정리했다. 실제 설치 전에는 최신 문서에서 패키지 이름, 지원 버전, 호환성 변경, 샌드박스 설정과 요금 조건을 다시 확인해야 한다.

Vercel Blog: Program Claude Code, Codex, Pi and other agent harnesses with AI SDK