ACP라서 같은 기능은 아니다: 전용 어댑터와 범용 어댑터의 권한·출력 경계

코딩 에이전트를 같은 인터페이스로 연결하고 싶을 때, 범용 프로토콜은 매력적이다. 하지만 연결할 수 있다는 사실과 필요한 기능이 같은 방식으로 작동한다는 사실은 다르다. JSON Schema를 지키는 출력이 필요하거나 읽기 전용 권한이 필수인 서비스라면, 첫 응답을 받았다는 이유만으로 통합을 끝낼 수 없다.

먼저 결론부터 정리하자. Vercel은 Claude Code와 Codex에는 전용 어댑터를 우선 권한다. 전용 어댑터가 없고 ACP 호환 구현이 제공되는 하네스에 범용 ACP 어댑터를 사용하는 것이 발표의 선택 기준이다. 여기서 전용은 특정 런타임에 맞춘 통합을 뜻한다. 특정 모델이 더 빠르거나 더 저렴하거나 더 안전하다는 실험 결과를 뜻하지 않는다.

이 글은 2026년 8월 13일 발표와 2026년 10월 23일 수집한 공식 문서 스냅샷을 구분해서 읽는다. 제품 사용 후기 대신, 연결 방식과 필수 기능을 함께 판단하는 결정표와 실패 진단 순서를 제공한다.

1. 범용 어댑터가 공통화하는 것은 연결 경로다

기존 하네스 어댑터는 특정 런타임을 감싼다. 반면 @ai-sdk/harness-acp는 Agent Client Protocol을 감싼다. HarnessAgent와 ACP 호환 구현 사이에서 브리지, 이벤트 변환, 승인 요청, 도구 중계, 수명주기를 연결하고, 런타임별 설치·실행·설정 차이는 프로필에 담는 구조다.

이 구조는 런타임마다 애플리케이션의 바깥 연결 코드를 새로 작성하는 부담을 줄이려는 접근으로 이해할 수 있다. 그렇다고 모든 하네스가 ACP를 제공하는 것도 아니며, 공통 연결 계층이 각 런타임 내부 동작을 빠짐없이 드러내는 것도 아니다. 발표 역시 ACP가 내부 동작 노출을 제한하거나 바꿀 수 있어 전용 어댑터가 더 밀접한 통합을 제공할 수 있다고 설명한다.

Claude Code·Codex는 전용 어댑터 우선. 범용 ACP는 전용 경로가 없고 ACP 구현이 있을 때 검토한다. 성능 비교 결과가 아닌 발표의 선택 기준이다. 출처: vercel.com/changelog/use-acp-compatible-harnesses-with-the-ai-sdk-harness-layer.

다음 표는 공식 권고에 요구사항 검토를 더한 편집 분석이다. 구현을 실행해서 얻은 호환성 성적표는 아니다.

지금의 상황	먼저 선택할 경로	결정 전에 남는 확인
Claude Code 또는 Codex를 연결한다	해당 전용 어댑터를 우선 검토	그 경로에서도 필요한 기능·권한을 별도로 확인
전용 어댑터가 없고 ACP 호환 구현이 있다	범용 ACP 어댑터와 런타임 프로필 검토	모델 매핑, 구조화 출력, 권한, 자격 증명 경계
전용 어댑터도 ACP 구현도 확인되지 않는다	이 발표만으로 연결 가능하다고 판단하지 않음	별도 통합 경로의 근거 필요
ACP 연결은 되지만 필수 기능이 빠진다	요구를 충족하는 다른 경로 검토	권한 확대를 기능 지원의 대용으로 쓰지 않음

필수 기능이 빠졌다면 연결 방식을 재검토한다. 권한을 넓혀서 기능 부족을 덮지 않는다.

2. JSON이 보인다고 구조화 출력 지원은 아니다

보관 문서가 지원한다고 밝힌 프로토콜은 ACP v1이다. 여기서 1은 프로토콜 버전이지 패키지의 주 버전이나 성능 점수가 아니다. 문서는 하네스 패키지를 실험 단계로 표시하고 릴리스 사이의 호환성 파괴 가능성을 경고한다.

특히 ACP v1 자체에는 구조화 출력 기능이 표준화되어 있지 않다. 선택한 구현이 비공개 확장을 문서화한 경우에만 outputSchemaMapping 같은 구현별 매핑을 명시할 수 있다. 이 매핑이 없는 프로필에서 HarnessAgent의 구조화 출력을 요구하면 문서상 HarnessCapabilityUnsupportedError가 발생한다. 현재 보관 문서는 Codex ACP의 구조화 출력을 미지원으로 표시한다. 이를 Codex의 모든 연결 방식이나 전용 어댑터 전체에 대한 결론으로 확대하면 안 된다.

ACP v1 연결이 구조화 출력이나 모든 권한 모드의 지원을 보장하지 않는다. 미지원 매핑은 오류이며 요구사항 재검토의 신호다. 출처: ai-sdk.dev/providers/ai-sdk-harnesses/acp.

예를 들어 작업 분류 결과를 고정된 필드로 저장하는 애플리케이션을 생각해 보자. 일반 대화에서 JSON처럼 보이는 문자열이 한 번 나왔다고 해서 스키마 강제 지원이 입증되지는 않는다. 설계 단계에서는 출력 요구를 먼저 적고, 해당 프로필이 그 요구를 전달하는 공식 매핑을 제공하는지 확인해야 한다. 문서상의 미지원과 실제 잘못된 출력은 서로 다른 문제이며, 이 글에서는 출력 정확도 실험을 하지 않았다.

3. 권한 모드의 null은 승인으로 바꿀 빈칸이 아니다

Harness의 권한 모드는 allow-reads, allow-edits, allow-all 세 가지다. ACP 구현이 네이티브 권한 제어를 노출해서 명시적 매핑을 설정하는 경우에는 세 모드를 모두 대응시키고, 지원하지 않는 항목은 null로 표시한다. 이 null 매핑을 선택하면 문서상 미지원 오류가 발생한다.

중요한 구분이 있다. 명시적 매핑의 항목이 null인 것과 매핑 설정 자체를 생략한 것은 같지 않다. 매핑을 생략하면 어댑터는 도구 종류와 permissionMode에 따라 허용 가능한 요청을 처리하고 나머지에 Harness 승인을 요청하는 경로를 사용한다. 따라서 “ACP는 언제나 세 모드의 네이티브 기능을 제공한다”거나 “매핑이 없으면 전부 거부된다”는 요약은 모두 부정확하다.

읽기 전용이 필수인 애플리케이션에서 특정 프로필이 그 모드를 제공하지 않는다면, 오류를 없애려고 allow-all로 바꾸는 것은 요구사항을 해결한 것이 아니다. 호출이 통과하도록 만든 것과 사용자가 승인한 범위 안에서 동작하게 만든 것은 다른 목표다. 별도의 호스트 도구 승인도 여전히 남는다.

4. 샌드박스 밖의 도구와 비밀을 따로 본다

ACP 하네스에는 적어도 하나의 노출 포트를 가진 네트워크 샌드박스가 필요하다고 문서는 설명한다. 그러나 호스트가 정의한 AI SDK 도구는 하네스가 소유한 MCP 서버로 노출되며 실행 위치는 호스트다. ACP 프로세스가 샌드박스 안에 있다는 이유로 호스트 도구까지 자동 격리되었다고 판단할 수 없다.

호스트 도구는 호스트에서 실행된다. 대체 자격 증명은 샌드박스의 요청 변환 지원이 조건이며, 값 전달 제어와 호스트의 비밀 접근 제한은 다르다. 출처: ai-sdk.dev/providers/ai-sdk-harnesses/acp.

자격 증명도 같은 방식으로 경계를 나눠야 한다. 현재 보관 문서는 forwardEnv를 비자격 증명 설정용으로 두고, 자격 증명은 credentialEnv와 credentialBrokering으로 처리하도록 설명한다. 네트워크 샌드박스가 추가 요청 변환을 지원하면 ACP 프로세스에는 기본적으로 일시적 대체값을 전달하고, 샌드박스 밖으로 나가는 요청에서 조건이 맞을 때 실제 값을 주입하는 방식이다.

이 설명에서 조건절을 빼면 결론이 바뀐다. 해당 기능을 지원하지 않는 샌드박스에는 실제 값을 전달하는 이전 동작이 남는다고 문서가 명시한다. 따라서 “비밀이 어떤 샌드박스에도 절대 들어가지 않는다”는 주장은 근거가 없다. 또한 credentialForwarding은 프로세스에 전달하는 값만 바꾸며, 호스트 프로세스에서 어댑터가 어떤 자격 증명을 읽을 수 있는지까지 제한하지 않는다.

실무적으로는 도구 실행 위치, 그 도구의 승인 주체, 샌드박스에 들어가는 값, 호스트가 읽을 수 있는 값을 각각 적어 보는 편이 낫다. 이는 문서의 경계를 설계 검토에 적용한 제안이며, 특정 구성에 대한 보안 인증은 아니다.

5. 발표 예시는 현재 설정의 복사 원본이 아니다

원 발표의 짧은 예시는 npm-simple과 forwardEnv의 자격 증명 이름을 보여 준다. 반면 이번에 보관한 문서는 잠긴 NPM 설치나 신뢰한 설치 명령을 설명하고, 자격 증명 전달과 일반 환경 설정을 분리한다. 발표의 목적과 현재 설정 문서의 역할이 다르다는 점이 드러나는 대목이다.

발표 예시는 npm-simple과 forwardEnv의 키 이름을 보여 주지만, 보관 문서는 설치 고정과 자격 증명 분리를 설명한다. 문서 차이이지 취약점 재현 증거는 아니다. 출처: ai-sdk.dev/providers/ai-sdk-harnesses/acp.

잠긴 설치는 설치 구성을 고정하는 경로다. 설치 명령 경로는 명령 자체를 실행 가능한 설정으로 다뤄야 하고 자동으로 버전을 고정해 주지 않는다는 주의도 있다. 오래된 발표 코드를 현재 API에 그대로 붙인 뒤 오류만 수정하는 방식보다는, 실제 사용 버전에 대응하는 문서에서 프로필과 설치 근거를 다시 맞추는 것이 합리적이다.

이 차이를 발견했다고 해서 과거 예시에 확인된 취약점이 있었다거나 현재 구성의 안전성을 입증했다고 말할 수는 없다. 여기서 확인한 것은 보관한 두 공식 본문의 차이이며, 과거 설치 버전의 동작을 재현한 결과가 아니다.

6. 연결 실패를 고칠 때 질문의 순서를 바꾼다

다음은 문서 분석을 바탕으로 만든 진단 순서다. 그대로 실행할 프로그램이나 검증 완료된 설정 파일은 아니다.

1. 사용할 런타임에 전용 어댑터가 있는지 확인한다. Claude Code·Codex라면 발표의 전용 우선 권고부터 적용한다.
2. ACP가 필요한 경우에는 해당 구현의 설치 근거와 모델 매핑을 정한다. 단순히 프로토콜 이름이 같다는 이유로 다른 런타임의 프로필을 복사하지 않는다.
3. 저장 결과에 스키마 강제가 필수인지, 읽기 전용 같은 권한 요구가 필수인지 적는다. 각 요구에 공식 지원 근거가 있는지 분리해서 본다.
4. 미지원 출력이나 null 권한 매핑이라면 요구와 경로의 불일치를 해결한다. 권한을 넓히는 것으로 검사를 통과시키지 않는다.
5. 호스트 도구의 실행 위치·승인과 자격 증명 전달을 따로 검토한다. 샌드박스 하나로 모든 경계를 설명하지 않는다.

이 글은 공식 발표와 보관한 문서 스냅샷의 분석이며, 패키지 설치·실행이나 성능·비용·보안의 독립 검증을 수행하지 않았다. AI를 활용해 공개 자료를 정리하고 결정표·도식을 작성했다. 속도, 비용 절감률, 출력 성공률을 새로 측정한 수치는 없다.

결국 범용 ACP의 가치는 모든 하네스를 동일하게 만드는 데 있지 않다. 공통 연결 경로를 만들되, 실제 기능과 실행 권한의 차이는 드러난 상태로 남긴다는 점에 있다. 좋은 통합의 기준은 첫 응답의 성공이 아니라, 애플리케이션의 필수 요구와 각 경계가 일치하는지다.

참고 자료

• Vercel 원 발표: 프로토콜 어댑터의 취지와 전용 어댑터 우선 선택 기준.
• AI SDK ACP 공식 문서: 이번 글이 분석한 구조화 출력·권한·인증·샌드박스 설정. 변경될 수 있으므로 글의 기준은 보관한 2026년 10월 23일 스냅샷이다.