JetBrains Air의 GitHub Copilot 기본 통합 해부: Agent Client Protocol(ACP) 양방향 stdio 통신과 프레이밍 검증

JetBrains Air(클라이언트)와 GitHub Copilot CLI(에이전트 서브프로세스)가 Agent Client Protocol(ACP)의 양방향 JSON-RPC 2.0(stdio) 채널로 세션을 제어하고 파일·권한 RPC를 주고받는 구조를 정리한 개념 요약도다. 실제 IDE 화면이 아니다.

2026년 11월 3일 GitHub와 JetBrains가 에이전트 중심 개발 환경인 JetBrains Air에 GitHub Copilot을 기본(Built-in) 에이전트로 통합했다고 발표했다. 개발자는 별도의 JetBrains AI 크레딧을 소모하지 않고 기존 GitHub Copilot 구독 플랜을 그대로 연결해 로컬 IDE 작업이나 클라우드 샌드박스(Air Teams) 작업을 위임할 수 있다. GitHub Changelog 발표, JetBrains 공식 블로그 발표

결론부터 말하면, 이번 통합의 핵심은 특정 IDE 전용 플러그인을 또 만든 것이 아니라 에디터와 코딩 에이전트 사이의 오픈 표준인 Agent Client Protocol(ACP) 위에서 GitHub Copilot CLI를 서브프로세스로 구동한 데 있다. ACP는 표준 입출력(stdio) 위에서 개행(Newline)으로 구분되는 양방향 JSON-RPC 2.0 메시지를 주고받으며, 에이전트가 에디터에게 역방향으로 파일 읽기·쓰기(fs/read_text_file, fs/write_text_file)와 도구 실행 승인(session/request_permission)을 요청하는 구조다. 따라서 커스텀 에이전트나 래퍼 스크립트를 ACP로 연결할 때 stdout에 일반 디버그 로그나 배너가 단 한 줄이라도 섞이면 세션 파서가 즉시 중단된다는 점을 가장 먼저 통제해야 한다.

이 글은 GitHub·JetBrains의 공식 발표와 Agent Client Protocol 공식 명세를 바탕으로 로컬·클라우드 실행 구조, 양방향 JSON-RPC 2.0 메서드 흐름, 그리고 로컬 Python 검증기로 확인한 프레이밍·권한 게이트 규칙을 정리한다. 실제 JetBrains Air Teams 클라우드 과금 정산이나 대규모 프로젝트 응답 지연 시간은 직접 측정하지 않았다.

1. 기존 IDE 플러그인 방식과 JetBrains Air의 ACP 통합이 다른 점

기존에는 새로운 코딩 에이전트가 나올 때마다 VS Code, JetBrains, Zed, Neovim 등 각 에디터 전용 확장(Extension)을 별도로 개발하고 UI·파일 접근·권한 승인 로직을 중복 구현해야 했다. 반면 Agent Client Protocol(ACP)은 Language Server Protocol(LSP)이 언어 분석기를 표준화한 것처럼 코드 에디터(Client)와 코딩 에이전트(Agent) 사이의 통신 규약을 단일 JSON-RPC 2.0 프로토콜로 표준화한다.

구분 항목	기존 IDE 전용 플러그인 결합	JetBrains Air + ACP 기반 통합
프로세스 구동 및 통신	IDE 내부 API에 강하게 결합된 전용 플러그인 런타임	에디터(Client)가 에이전트 CLI(예: `copilot --acp`)를 서브프로세스로 띄우고 `stdio` 기반 JSON-RPC 2.0으로 통신
다중 에이전트 병렬 실행	플러그인별 개별 패널·상태 관리로 동시 실행 및 비교가 번거로움	단일 에이전트 픽커(Agent Picker)에서 GitHub Copilot, Claude Agent, Codex, Gemini, Junie 등을 나란히 실행하고 세션별로 격리
실행 위치 (Local vs Cloud)	주로 로컬 IDE 프로세스 내부에 종속	로컬 워크스페이스 실행뿐 아니라 Air Teams 클라우드 샌드박스에 작업을 위임해 노트북을 닫아도 원격 실행 지속
과금 및 인증 체계	통합 환경의 자체 크레딧과 개별 구독이 혼재	기존 GitHub Copilot 구독(Pro, Pro+, Business, Enterprise) 계정으로 직접 로그인해 Copilot 플랜 한도 내에서 동작

특히 기존 JetBrains용 GitHub Copilot 플러그인과 배타적 관계가 아니므로, 일상적인 인라인 코드 자동완성은 기존 플러그인으로 유지하면서 다중 파일 리팩터링이나 병렬 이슈 해결 같은 장기 에이전트 태스크만 JetBrains Air의 ACP 세션으로 분리해 운영하는 구성이 가능하다.

2. ACP 양방향 JSON-RPC 2.0 프로토콜 흐름 해부

ACP에서 에디터는 단순히 프롬프트만 던지고 텍스트 스트림만 받는 수동적 클라이언트가 아니다. 초기화 단계에서 서로의 지원 기능(Capabilities)을 협상한 뒤, 에이전트가 작업 도중 에디터의 파일 시스템(열려 있는 버퍼 포함), 터미널, 사용자 승인 UI를 역방향 RPC로 호출하는 양방향 구조를 갖는다.

단계 및 방향	JSON-RPC 메서드	요청/알림 구분	핵심 파라미터 및 동작 규칙
1. 초기화 협상 (Client → Agent)	`initialize`	Request	`protocolVersion`(정수 버전), `clientCapabilities`(`fs.readTextFile`, `fs.writeTextFile`, `terminal` 지원 여부)를 전달하고 에이전트의 지원 기능 및 인증 방식 목록을 응답받음
2. 세션 생성 (Client → Agent)	`session/new`	Request	작업 디렉터리 절대 경로(`cwd`)와 연결할 MCP 서버 목록(`mcpServers`)을 전달해 격리된 `sessionId`를 발급받음 (`loadSession` 지원 시 `session/load`로 기존 세션 복원 가능)
3. 프롬프트 전달 (Client → Agent)	`session/prompt`	Request	`sessionId`와 사용자 지시문·코드 리소스·이미지 블록 배열(`prompt`)을 전달해 에이전트 추론 루프를 시작함
4. 실시간 진행 알림 (Agent → Client)	`session/update`	Notification	응답 ID 없이 단방향으로 추론 계획(`plan`), 메시지 청크(`agent_message_chunk`), 도구 호출 상태 및 파일 diff(`tool_call`, `tool_call_update`)를 실시간 스트리밍함
5. 역방향 승인 게이트 (Agent → Client)	`session/request_permission`	Reverse Request	파일 수정이나 셸 명령 실행 전 에디터에 승인을 요청함. 사용자가 에디터 UI에서 선택하면 `outcome: {\"outcome\": \"selected\", \"optionId\": \"...\"}` 또는 취소 시 `{\"outcome\": \"cancelled\"}`를 반환함
6. 역방향 파일·터미널 접근 (Agent → Client)	`fs/read_text_file`, `fs/write_text_file`, `terminal/create`	Reverse Request	에이전트가 디스크 파일을 직접 읽는 대신 에디터에 파일 읽기·쓰기를 위임해 저장되지 않은 에디터 버퍼 상태까지 일관되게 반영하고 수정 내역을 IDE diff 뷰어에 즉시 연결함

만약 사용자가 프롬프트 실행 도중 취소 버튼을 누르면, 에디터는 session/cancel 알림(Notification)을 보내고 에이전트는 진행 중인 모든 역방향 도구·권한 요청을 중단한 뒤 현재 session/prompt 요청을 stopReason: \"cancelled\"로 즉시 종료해야 한다.

3. 실무에서 가장 흔한 장애 원인: `stdout` 오염과 역방향 Capability 누락

커스텀 에이전트나 사내 래퍼 스크립트를 ACP 규격으로 JetBrains Air나 Zed에 연결할 때 가장 빈번하게 발생하는 오류는 두 가지다.

stdout 비-JSON 출력으로 인한 스트림 파서 중단: ACP의 stdio 전송 계층은 에이전트 서브프로세스의 stdout에서 개행(\n)으로 구분된 단일 라인 UTF-8 JSON-RPC 메시지만 읽는다. 메시지 본문 안에 이스케이프되지 않은 개행이 들어가거나, 셸 초기화 스크립트·Node/Python 로거가 stdout에 배너나 디버그 문자열을 출력하면 에디터의 JSON-RPC 파서가 즉시 깨진다. 모든 진단 로그와 진행 배너는 반드시 stderr로만 출력해야 한다.

협상되지 않은 역방향 메서드 호출: 에이전트가 initialize 단계에서 클라이언트가 fs.readTextFile: true나 terminal: true를 선언했는지 확인하지 않고 fs/read_text_file을 호출하면 -32601 Method not found 오류가 발생한다. 클라이언트 Capability 스냅샷을 세션 상태에 보관하고 지원 여부에 따라 폴백 경로를 두어야 한다.

4. 로컬 Python으로 구현·검증하는 ACP 양방향 프레이밍 및 승인 시뮬레이터

다음 코드는 외부 패키지 없이 Python 표준 라이브러리만으로 구현한 ACP stdio 메시지 검증기(acp_stdio_simulator.py)다. ① 초기화 전 세션 호출 차단, ② 단일 라인 JSON-RPC 프레이밍 및 stdout 오염 탐지, ③ 에이전트→IDE 역방향 권한 승인(session/request_permission) 및 Capability 기반 파일 접근(fs/read_text_file)을 검증한다.

직접 실행해 확인한 범위

로컬 환경에서 python acp_stdio_simulator.py를 실행해 다음 5개 검사가 모두 통과(5 checks passed)함을 확인했다.

초기화 전 세션 생성 차단: initialize 핸드셰이크 전에 session/new를 호출하면 -32002 Server not initialized 오류를 반환한다.

버전 협상 및 세션 발급: initialize 완료 후 session/new 호출 시 정상적으로 sess_3 식별자가 생성된다.

역방향 권한 승인 및 에디터 파일 읽기: 에이전트가 클라이언트로 보낸 session/request_permission과 fs/read_text_file 요청이 정책과 Capability 설정에 맞춰 응답한다.

stdout 비-JSON 배너 오염 즉시 탐지: "Starting Copilot CLI agent v1.0...\n"처럼 JSON-RPC 프레임이 아닌 일반 문자열이 stdout에 유입되면 즉시 ACP_STDOUT_POLLUTION 예외로 잡아낸다.

비활성화된 클라이언트 Capability 호출 거부: fs.readTextFile이 False일 때 에이전트가 파일 읽기를 시도하면 -32601 오류로 차단한다.

5. JetBrains Air 및 ACP 에이전트 도입 시 점검 체크리스트

로컬 실행과 클라우드 샌드박스(Air Teams)의 환경 분리: 로컬 IDE에서 Copilot 에이전트를 실행할 때는 개발자 PC의 파일 시스템과 로컬 MCP 서버에 직접 접근하지만, Air Teams 클라우드 환경으로 태스크를 넘기면 격리된 컨테이너에서 실행되므로 사내 프라이빗 패키지 저장소 토큰이나 환경 변수가 샌드박스 프로파일에 주입되어 있는지 먼저 확인해야 한다.

래퍼 스크립트의 stdout 출력 리다이렉션 점검: 사내 보안 감사를 위해 에이전트 실행 전후에 셸 래퍼를 씌운다면, 래퍼 내부의 모든 echo나 로깅 출력을 >&2(stderr)로 보내야 ACP 세션이 끊기지 않는다.

Copilot 엔터프라이즈 정책 및 BYOK 구분: 조직 계정의 GitHub Copilot을 JetBrains Air에 연결할 때는 리포지토리 루트의 커스텀 지침(AGENTS.md, .github/copilot-instructions.md)과 엔터프라이즈 모델 정책이 동일하게 적용되는지 첫 session/prompt 테스트에서 확인하는 편이 안전하다.