Vercel AI SDK의 ACP 코딩 에이전트 어댑터, 제대로 이해하기

Vercel이 실제로 내놓은 것

먼저 흔히 뒤섞이는 계층부터 구분해 보겠습니다.

모델은 다음 응답을 생성합니다. 하네스는 세션, 툴, 승인, 샌드박스, 지시사항, 컨텍스트 압축, 작업 루프를 관리해 그 모델을 실제 작업자로 바꿉니다. ACP는 Agent Client Protocol의 약자로, 클라이언트와 하네스가 공통된 방식으로 통신하게 해 줍니다.

Vercel의 HarnessAgent는 이미 애플리케이션이 여러 하네스를 하나의 API로 다룰 수 있게 했습니다. 빠져 있던 것은 연결부였습니다. 이번 릴리스 전까지 Vercel은 Claude Code, Codex, Pi, Deep Agents, OpenCode를 비롯한 런타임마다 별도의 어댑터를 만들어야 했습니다.

새 ACP 하네스 어댑터는 특정 런타임이 아니라 프로토콜을 감쌉니다. 하네스에서 ACP를 구현하는 NPM 패키지와 실행 파일, 인증 규칙, 지시사항 매핑, 권한 매핑을 createACP에 넘기면 됩니다. 그러면 범용 어댑터가 브리지, ACP 클라이언트, 툴 릴레이, 이벤트, 승인, 세션 라이프사이클을 처리합니다.

구조의 핵심은 이 역할 분담입니다. 공통 브리지는 Vercel이 맡고, 하네스별로 달라지는 세부 사항은 런타임 프로필이 맡습니다.

현재 어댑터가 지원하는 버전은 ACP version 1, 오직 version 1뿐입니다. 프로토콜 경계에서의 호환성을 제공한다는 뜻이지, 연결한 뒤 모든 하네스가 똑같이 동작한다는 보장은 아닙니다.

Vercel은 선택 기준도 분명히 밝혔습니다. Claude Code와 Codex에는 각각 @ai-sdk/harness-claude-code 또는 @ai-sdk/harness-codex를 사용합니다. 호환 패키지는 있지만 직접 어댑터가 없는 하네스에는 @ai-sdk/harness-acp를 사용합니다.

코딩 에이전트 통합에서 중요한 이유

이번에 달라진 핵심은 통합 작업량입니다.

개발자 툴 팀은 이제 다른 ACP 런타임을 HarnessAgent 뒤에 붙이기 위해 세션 처리, 이벤트 변환, 승인 연결, 호스트 툴 릴레이, 라이프사이클 동작을 처음부터 다시 만들 필요가 없습니다. 런타임 프로필만 작성하면 나머지 애플리케이션은 같은 하네스 API를 계속 사용할 수 있습니다.

제품 계층도 그대로 지킬 수 있습니다. HarnessAgent.generate()와 HarnessAgent.stream()은 모두 AI SDK 호환 결과를 반환합니다. 이미 useChat을 쓰는 팀이라면 뒤에서 일하는 워커를 바꾸더라도 기존 인터페이스 흐름을 유지할 수 있습니다.

이번 릴리스가 하네스를 더 빠르거나 저렴하거나 강력하게 만들어 주는 것은 아닙니다. ACP 구현을 서로 똑같게 만들지도 않으며, 샌드박스를 대체하지도 않습니다. 모든 ACP 하네스에는 여전히 최소 하나의 포트를 노출한 네트워크 샌드박스가 필요합니다.

Claude Code, Codex 또는 다른 코딩 에이전트를 직접 사용하는 사람에게는 대부분 영향이 없습니다. 이 기능은 그런 에이전트 주변에 제품을 만드는 사람을 위한 것입니다.

누가 당장 활용할 수 있나

AI SDK 지원을 추가하려는 개발자 툴 창업자

회사가 코딩 하네스를 제공하고 이미 ACP 호환 NPM 패키지를 배포하고 있다고 가정해 보겠습니다. 이제 createACP 프로필 하나를 정의해 AI SDK 사용자에게 해당 런타임으로 들어가는 공식 지원 경로를 제공할 수 있습니다.

실질적인 이점은 배포 경로가 넓어진다는 것입니다. 패키지별 설치, 인증, 지시사항, 권한은 해당 팀이 관리하고, 그 주변의 공통 연결 작업은 Vercel 어댑터가 처리합니다.

여러 런타임을 지원하는 플랫폼 엔지니어

중간 규모의 엔지니어링 플랫폼이라면 저장소 수정에는 한 에이전트, 마이그레이션 작업에는 다른 에이전트, 사내 전용 자동화에는 내부 하네스를 쓰고 싶을 수 있습니다. 플랫폼 엔지니어는 하나의 세션 및 결과 계약을 유지하면서 작업마다 다른 하네스 프로필을 선택할 수 있습니다.

그렇다고 동작 차이가 사라지는 것은 아닙니다. 차이를 이름이 붙은 프로필 안으로 옮겨, 별도의 오케스트레이션 스택 여러 개보다 쉽게 검토할 수 있게 만드는 방식입니다.

기존 AI SDK 인터페이스를 쓰는 SaaS 팀

제품 팀은 채팅 화면을 다시 만들지 않고도 기존 AI SDK 애플리케이션 뒤에 ACP 기반 코딩 워커를 추가할 수 있습니다. 구체적인 변경은 서버에서 이뤄집니다. 하네스 프로필을 만들고 샌드박스를 연결해 세션을 시작한 뒤, UI가 이미 처리하는 것과 같은 유형의 스트리밍 또는 생성 결과를 반환하면 됩니다.

제품에 통합하는 단계가 아니라 아직 에이전트 자체를 고르는 중이라면 코딩 에이전트 비교부터 확인하는 편이 좋습니다. 이 어댑터는 그 제품 결정이 끝난 다음에 의미가 있습니다.

경계를 설계하는 보안 엔지니어

보안 엔지니어에게는 통제 지점이 명확해집니다. 자격 증명을 중개하면 샌드박스 안의 ACP 프로세스에는 자리표시자만 보이고, 실제 값은 외부로 나가는 요청에 추가되도록 구성할 수 있습니다. 권한 모드는 런타임이 실제로 지원하는 모드에 맞춰 매핑할 수 있으며, 지원하지 않는 선택지는 null로 지정해 접근 범위가 조용히 넓어지는 대신 실패하게 만들 수 있습니다.

그 결과 안전이 자동으로 보장되는 것은 아닙니다. 다만 안전 규칙을 코드로 만들고 테스트할 위치가 분명해집니다.

도입 절차

문서에 나온 전체 예제

하네스와 ACP 어댑터, Vercel Sandbox 패키지를 설치합니다.

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

핵심을 빠뜨리지 않으면서 가장 간결한 데모는 Vercel의 전체 Codex ACP 프로필입니다. 패키지 설치, 직접 자격 증명, AI Gateway 구성, 지시사항, 권한을 한곳에서 보여 주기 때문입니다. 이는 연결 구조를 보여 주는 예제이지, Codex에 ACP를 선택하라는 권장은 아닙니다. 실제 Codex 통합에는 Vercel이 직접 Codex 어댑터를 우선합니다.

아래 코드는 현재 문서에 실린 프로필과 호출 흐름입니다. 직접 인증을 사용하려면 CODEX_API_KEY 또는 OPENAI_API_KEY를 제공해야 합니다. AI_GATEWAY_API_KEY나 VERCEL_OIDC_TOKEN을 제공하면 기본 auth: 'auto' 경로가 대신 AI Gateway를 선택합니다.

import { createACP, type ACPPermissionModeMapping } from '@ai-sdk/harness-acp';
import { createCredentialRequestTransformation } from '@ai-sdk/harness/utils';
import { secureJsonParse } from '@ai-sdk/provider-utils';

export const codexACPHarness = createACP({
  harnessId: 'acp-codex',
  // Define the runtime's built-in tool names and input schemas to expose
  // provider-executed calls as typed HarnessAgent tools.
  // builtinTools: { ... },
  source: {
    type: 'npm-simple',
    packageName: '@agentclientprotocol/codex-acp',
    packageVersion: '1.1.4',
  },
  executable: 'codex-acp',
  forwardEnv: ['CODEX_CONFIG'],
  credentialEnv: ['CODEX_API_KEY', 'OPENAI_API_KEY'],
  credentialBrokering: ({ env }) => {
    const credential = env.CODEX_API_KEY ?? env.OPENAI_API_KEY;
    if (!credential) return [];
    const config =
      env.CODEX_CONFIG == null
        ? undefined
        : (secureJsonParse(env.CODEX_CONFIG) as {
            model_provider?: string;
            model_providers?: Record<string, { base_url?: string }>;
          });
    const baseUrl =
      config?.model_providers?.[config.model_provider ?? '']?.base_url ??
      'https://api.openai.com/v1';
    return [
      createCredentialRequestTransformation({
        baseUrl,
        headers: { Authorization: `Bearer ${credential}` },
      }),
    ];
  },
  instructionMapping: {
    type: 'launch-env-json',
    variable: 'CODEX_CONFIG',
    path: ['developer_instructions'],
  },
  permissionModeMapping: {
    'allow-reads': null,
    'allow-edits': null,
    'allow-all': { type: 'session-mode', modeId: 'agent-full-access' },
  } as const satisfies ACPPermissionModeMapping,
  authentication: {
    methodId: 'api-key',
  },
  providerAuthentication: {
    gateway: {
      env: {
        CODEX_API_KEY: { $source: 'gateway-api-key' },
        CODEX_CONFIG: {
          model: 'openai/gpt-5.6-sol',
          model_provider: 'ai_gateway',
          model_providers: {
            ai_gateway: {
              name: 'AI Gateway',
              base_url: {
                $source: 'gateway-base-url',
                ensureSuffix: '/v1',
              },
              env_key: 'CODEX_API_KEY',
              wire_api: 'responses',
              supports_websockets: false,
              http_headers: {
                'User-Agent': { $source: 'client-app' },
                'x-client-app': { $source: 'client-app' },
              },
            },
          },
          model_supports_reasoning_summaries: true,
          preferred_auth_method: 'apikey',
        },
      },
    },
  },
});

흔히 놓치는 지점은 런타임 프로필을 패키지 이름과 API 키의 조합으로만 보는 것입니다. 권한 매핑, 지시사항 매핑, 샌드박스 포트, 자격 증명 경계, 세션 정리까지 모두 통합의 일부입니다.

냉정하게 봐야 할 점

하네스 패키지는 실험 단계입니다. 릴리스 사이에 호환성을 깨는 변경이 생길 수 있으므로, 프로덕션에서 아무 검토 없이 버전이 올라가게 둘 만한 의존성은 아닙니다.

패키지 버전 고정 방식도 명시적으로 선택해야 합니다. 단순 소스 방식에서는 예제처럼 @agentclientprotocol/codex-acp를 정확히 1.1.4로 고정할 수 있습니다. 버전을 생략하면 샌드박스는 패키지의 latest 태그를 설치하며, 그 버전은 하네스 식별 정보에 포함되지 않습니다. 재현 가능한 빌드가 필요하다면 package.json과 pnpm-lock.yaml을 갖춘 잠금 소스를 사용해야 합니다. Vercel은 pnpm install --frozen-lockfile로 이를 설치합니다.

ACP version 1에는 다음과 같은 실질적인 공백도 있습니다.

• 모델 단계의 경계나 단계별 사용량을 노출하지 않습니다. 어댑터가 경계를 추론하며, 단계별 사용량은 알 수 없는 상태로 남습니다.
• 이식 가능한 수동 컨텍스트 압축 API나 턴 진행 중 개입 API가 없습니다.
• 하네스의 내장 툴을 이식 가능한 방식으로 필터링할 수 없습니다. 호스트 툴 필터링은 계속 작동하지만, ACP 내장 툴을 필터링하려 하면 오류가 발생합니다.
• 호스트 툴 목록이 바뀌면 ACP 구현이 MCP 툴 목록을 새로 불러와야 합니다. 오래된 목록을 쓰는 구현은 명시적으로 실패합니다.

이 릴리스를 위해 확인한 Vercel 페이지에는 @ai-sdk/harness-acp의 별도 가격이 명시돼 있지 않습니다. 이를 두고 “무료 에이전트”라고 해석해서는 안 됩니다. 이 아키텍처에는 여전히 모델 인증 경로와 필수 네트워크 샌드박스가 포함되므로, 기존 런타임 비용과 통제 방식은 그대로 적용됩니다.

더 근본적인 한계는 충실도입니다. ACP는 공통 연결 방식을 제공하지만, 직접 어댑터는 하네스 고유 동작을 더 세밀하게 노출할 수 있습니다. 표준화는 통합 작업을 줄여 줄 뿐, 그 아래의 런타임까지 없애 주지는 않습니다.

지금 무엇을 해야 하나

판단 기준은 간단합니다.

직접 AI SDK 어댑터가 없는 ACP 호환 하네스를 운영하거나, 플랫폼 팀이 여러 ACP 런타임을 하나의 애플리케이션 계약 뒤에 배치해야 한다면 이번 주에 움직일 만합니다. 얇은 프로필을 만들고 패키지 버전을 고정한 뒤, 모든 권한과 실패 경로를 테스트합니다.

프로덕션 정책상 실험 단계 패키지를 받아들일 수 없거나, 정확한 단계별 사용량이 필요하거나, 수동 컨텍스트 압축과 턴 진행 중 개입이 핵심 통제 수단이라면 기다리는 편이 낫습니다.

Claude Code 또는 Codex를 사용한다면 직접 어댑터를 유지합니다. Vercel이 권장하는 경로가 이미 마련돼 있으며, 프로토콜 경계를 거치면서 줄어드는 동작도 더 적습니다.

모델을 직접 호출하거나, 최종 사용자로서 코딩 에이전트를 사용하거나, 자체 애플리케이션 안에서 하네스를 실행할 필요가 없다면 이번 변화의 영향을 받지 않습니다.

팀의 제품 개발 방식을 바꾸는 툴을 쉬운 말로 계속 살펴보고 싶다면 뉴스레터에 가입하세요.