3.5. ACP 서버¶
ACP(Agent Communication Protocol) 서버를 사용하면 Backend.AI GO를 완전한 ACP 에이전트로 동작시킬 수 있습니다. Zed 편집기와 같은 ACP 클라이언트는 stdio를 통해 연결한 뒤, 로컬에서 실행 중인 모델과 Cowork 에이전트에 작업을 위임할 수 있습니다.
ACP란 무엇인가요?¶
ACP(Agent Communication Protocol)는 AI 에이전트를 조합하기 위한 개방형 표준입니다. ACP를 지원하는 클라이언트는 각 에이전트에 맞는 통합 코드를 별도로 작성하지 않아도, 호환되는 에이전트 어디에나 프롬프트와 도구 호출을 위임할 수 있습니다.
Backend.AI GO는 ACP 서버 역할을 담당합니다. ACP 클라이언트로부터 요청을 받아 Cowork의 추론 루프(설정된 도구 및 권한 포함)를 통해 처리하고, ACP 형식으로 응답을 반환합니다.
ACP 서버를 사용하는 경우¶
- Zed 편집기를 사용하면서 클라우드 서비스 대신 로컬 모델을 활용하고 싶을 때.
- ACP를 지원하는 애플리케이션을 개발하면서 로컬 에이전트로 테스트하고 싶을 때.
- 원격 오케스트레이터의 에이전트 작업을 로컬 Backend.AI GO 인스턴스로 오프로드하고 싶을 때.
ACP 서버 활성화¶
- 설정 → ACP를 엽니다.
- ACP 서버 활성화 토글을 켭니다.
- (선택 사항) 에이전트 프로필을 선택합니다 — 프로필에 따라 시스템 프롬프트와 ACP 세션의 기본 권한 정책이 결정됩니다.
- (선택 사항) 클라이언트가 모델을 지정하지 않을 경우 사용할 기본 모델을 설정합니다.
- 시작을 클릭합니다.
서버가 준비되면 상태 배지가 중지됨에서 실행 중으로 변경됩니다.
프로필 선택 권장
프로필을 선택하는 것을 권장합니다. 프로필이 없으면 ACP 세션은 전역 ACP 권한 설정을 사용하며, 대부분의 도구 종류에 대해 기본값인 ask가 적용됩니다. 프로필을 사용하면 ACP 클라이언트가 호출할 도구를 미리 승인하여 불필요한 권한 확인 요청을 줄일 수 있습니다.
ACP 세션 동작 방식¶
ACP 서버가 실행되면 --mode stdio 모드로 continuum-router 서브프로세스를 시작합니다. 연결하는 각 ACP 클라이언트는 개별 세션을 받습니다. 세션은 고유 ID로 식별되며, 활성 프로필(또는 선택된 프로필이 없는 경우 ACP 권한 설정)에서 생성된 권한 구성을 공유합니다.
세션은 설정 → ACP의 세션 모니터 섹션에서 확인할 수 있습니다:
- 현재 활성 세션 수.
- 각 세션의 ID, 연결된 클라이언트 이름/버전, 생성 시각, 마지막 활동 시각, 프롬프트 횟수, 도구 호출 횟수.
권한 모델¶
ACP 권한 모델은 Cowork의 도구 권한 시스템을 반영합니다. 관련 구성 키는 다음과 같습니다:
| 키 | 타입 | 설명 |
|---|---|---|
default_policy | ask | allow_all | allow_read | 종류 또는 도구별 규칙이 일치하지 않을 때의 기본 정책 |
auto_allow_kinds | 종류 문자열 목록 | 확인 없이 실행되는 도구 종류 (예: read, search, think) |
always_ask_kinds | 종류 문자열 목록 | 항상 승인이 필요한 도구 종류 (예: edit, delete, execute) |
tool_overrides | 도구 이름 → 정책 맵 | 도구별 재정의; 종류 기반 규칙보다 우선 적용 |
정책은 다음 순서로 결정됩니다 (높은 우선순위 순):
- 도구별 재정의 (설정 → ACP → 권한 또는 선택된 프로필에서 지정).
- 종류 기반 제한적 정책 (
always_ask_kinds— 우발적 우회 방지를 위해 먼저 확인). - 종류 기반 허용적 정책 (
auto_allow_kinds). default_policy.
프로필이 활성화된 경우 해당 프로필의 도구 권한 재정의가 tool_overrides 맵에 반영되어 모든 ACP 세션에서 프로필의 의도가 적용됩니다.
acp-config.yaml 파일¶
ACP 서버는 직접 작성한 YAML 파일을 읽지 않습니다. 대신 Backend.AI GO가 시작 버튼을 클릭할 때(파일이 없는 경우) <app_data_dir>/acp-config.yaml을 자동으로 생성합니다. 생성된 파일에는 다음 정보가 포함됩니다:
- 설정에서 결정된
default_policy,auto_allow_kinds,always_ask_kinds. - 선택된 프로필에서 파생된 도구별 재정의.
이 파일을 직접 편집할 필요는 없습니다. 파일이 이미 존재하는 경우 ACP 설정이나 활성 프로필을 변경한 후 서버를 재시작하면 새 설정이 반영됩니다(기존 파일은 자동으로 덮어쓰지 않습니다).
기본 앱 데이터 디렉토리¶
| 플랫폼 | 경로 |
|---|---|
| macOS | ~/Library/Application Support/ai.backend.go/ |
| Windows | %APPDATA%\ai.backend.go\ |
| Linux | ~/.local/share/ai.backend.go/ |
세션 제한¶
| 설정 | 범위 | 기본값 | 설명 |
|---|---|---|---|
| 최대 동시 세션 수 | 1–100 | 10 | 동시에 허용되는 ACP 세션의 최대 수 |
| 유휴 시간 초과 | 1–1 440분 | 60분 | 활동이 없을 경우 세션이 종료되기까지의 시간 |
ACP 서버 중지¶
설정 → ACP에서 중지를 클릭하거나, ACP 서버 활성화 토글을 끕니다. 서브프로세스가 종료되기 전에 활성 세션이 정상적으로 종료됩니다.
REST / 헤드리스 사용¶
헤드리스 배포를 위해 Management API를 통해서도 ACP 생명 주기를 관리할 수 있습니다:
| 메서드 | 엔드포인트 | 설명 |
|---|---|---|
GET | /api/v1/acp/status | 현재 서버 상태 및 세션 수 |
POST | /api/v1/acp/start | ACP 서버 시작 |
POST | /api/v1/acp/stop | ACP 서버 중지 |
POST | /api/v1/acp/restart | 중지 후 재시작 |
GET | /api/v1/acp/settings | 현재 ACP 설정 읽기 |
PUT | /api/v1/acp/settings | ACP 설정 업데이트 |
GET | /api/v1/acp/sessions | 활성 세션 목록 |
인증은 다른 Management API 엔드포인트와 동일한 API 키 규칙을 따릅니다. 자세한 내용은 API 서버를 참조하세요.
문제 해결¶
"ACP config file not found" 오류¶
증상: 시작을 클릭했을 때 ACP config file not found: <경로>/acp-config.yaml 오류가 표시됩니다.
원인: Backend.AI GO는 시작을 클릭할 때 acp-config.yaml을 자동으로 생성합니다. 파일을 쓸 수 없는 경우 (예: 디스크 공간 부족 또는 읽기 전용 앱 데이터 디렉토리) 서버를 시작할 수 없습니다.
해결 방법:
- 설정 → ACP로 이동합니다.
- 시작을 클릭합니다 — 처음 시작할 때 설정 파일이 자동으로 생성됩니다.
- 오류가 계속 발생한다면 Backend.AI GO가 앱 데이터 디렉토리에 쓰기 권한이 있는지 확인하세요 (위의 기본 앱 데이터 디렉토리 참조).
ACP 서버는 시작되지만 클라이언트가 연결되지 않는 경우¶
- 설정 → ACP에서 상태 배지가 실행 중으로 표시되는지 확인합니다.
- ACP 클라이언트가 올바른 stdio 명령어 및 인자를 사용하도록 설정되어 있는지 확인합니다.
- 설정 → ACP → 세션 모니터에서 세션이 생성되었는지 확인합니다.
continuum-router서브프로세스의 시작 오류를 확인하기 위해 Backend.AI GO 로그를 검토합니다.
시작 직후 서버가 종료되는 경우¶
- 설정 → ACP를 열고 시작/중지 버튼 아래의 오류 메시지를 확인합니다.
continuum-router바이너리가 존재하는지 확인합니다: 설정 → 종속성 확인을 실행하거나 설치 프로그램을 다시 실행하세요.- 앱 데이터 디렉토리의 디스크 공간을 확인합니다 — YAML 파일에 쓰기가 가능해야 합니다.