CoCo CLI Agent Client Protocol(ACP) 지원

CoCo CLI Agent Client Protocol(ACP) 지원

CoCo CLI는 에디터와 IDE가 외부 에이전트를 로컬 하위 프로세스로 임베드할 수 있게 하는 개방형 표준인 ACP(Agent Client Protocol)를 구현해요. ACP 모드에서 CoCo를 실행하면 에디터가 세션을 구동하고 CoCo는 에이전트 응답, 도구 호출, 파일 diff를 stdin/stdout으로 스트리밍해요.

출처: CoCo CLI Agent Client Protocol (ACP) support

본문

ACP 지원 덕분에 개발 환경을 떠나지 않고도 ACP를 말하는 에디터 안에서 CoCo를 사용할 수 있어요.

지원되는 ACP 클라이언트

CoCo CLI는 모든 ACP 호환 클라이언트의 에이전트 백엔드로 사용할 수 있어요. 다음을 포함해요.

• Zed
• JetBrains IDE
• Neovim

Visual Studio Code의 경우 ACP 대신 Visual Studio Code용 Snowflake 확장을 사용해요.

에디터별 설정 단계는 아래 Zed 구성과 JetBrains IDE 구성을 참고하세요.

사전 요구 사항

ACP 클라이언트를 CoCo와 함께 사용하도록 구성하기 전에 다음을 확인하세요.

• CoCo CLI가 설치되어 PATH에 있어요. cortex --version을 실행해 확인해요.
• Snowflake 연결이 하나 이상 구성되어 있어요. cortex auth login을 실행하거나 ~/.snowflake/connections.toml에 연결을 구성해요.
• ACP 클라이언트가 ndjson(줄바꿈으로 구분된 JSON)을 사용해 stdio를 통해 외부 에이전트를 지원해요.

주의 ACP 모드는 인증을 요구하지 않아요. CoCo는 -c로 전달한 Snowflake 연결(또는 설정의 기본 cortexAgentConnectionName)을 사용해요. 에디터를 시작하기 전에 인증하세요.

ACP 모드에서 CoCo 시작하기

에디터는 acp serve 명령을 사용해 CoCo를 하위 프로세스로 시작해요. 일반적인 사용에서는 이 명령을 터미널에서 직접 실행하지 않아요. 에디터가 구성에 따라 이 명령을 실행해요.

cortex acp serve -c <connection_name> [--bypass] [-m <model>] [-w <workdir>]

명령 옵션

옵션	설명
-c, --connection <name>	사용할 Snowflake 연결. 생략하면 cortexAgentConnectionName 설정으로 기본 설정돼요.
--bypass	세션의 모든 도구 호출을 자동 승인해요. 관리자의 정책에 의해 제어되며 관리 설정을 참고해요.
-m, --model <model>	세션의 기본 모델을 재정의해요.
-w, --workdir <path>	에이전트의 작업 디렉터리. 기본값은 프로세스의 현재 작업 디렉터리.
--plugin-dir <path>	플러그인 디렉터리 또는 GitHub 리포지토리(owner/repo, owner/repo#branch 또는 URL). 반복할 수 있어요.

중요 CoCo는 프로세스의 stdin과 stdout을 통해 ACP를 말해요. cortex acp serve를 시작할 때 래퍼 스크립트, 셸 초기화 파일, 사전 실행 훅에서 stdout에 쓰지 마세요. stdout의 추가 출력은 프로토콜 스트림을 손상시켜요. 진단 출력은 stderr 또는 파일에 기록하세요.

ACP 클라이언트 구성하기

대부분의 ACP 클라이언트는 시작할 하위 프로세스를 설명하는 JSON 또는 TOML 블록을 허용해요. 최소 구성은 cortex 명령과 acp serve 인수를 지정해요.

{
  "command": "cortex",
  "args": ["acp", "serve", "-c", "my_connection"]
}

{
  "command": "cortex",
  "args": [
    "acp", "serve",
    "-c", "my_connection",
    "-m", "claude-sonnet-4-6",
    "-w", "/Users/me/projects/my-repo"
  ]
}

에디터가 에이전트 하위 프로세스에 환경 변수를 노출한다면 해당 메커니즘을 통해 Snowflake 자격 증명 재정의(예: SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER)를 전달할 수 있어요. CoCo는 ACP 클라이언트 프로세스의 환경을 상속해요.

Configure Zed

Zed에서 CoCo를 사용하려면 사용자 정의 외부 에이전트로 추가해요. 시작하기 전에 사전 요구 사항을 완료하고 cortex acp serve -c <connection_name>이 터미널에서 성공적으로 실행되는지 확인하세요.

아래 구성은 Zed 외부 에이전트 문서에 설명된 것과 같은 agent_servers 구조를 사용해요. 유일한 차이는 제네릭 에이전트 실행 파일 대신 Cortex Code의 ACP 하위 프로세스(cortex acp serve)를 시작하는 command와 args 값이에요.

1. Zed에서 agent: open settings을 실행해 Agent Settings를 열어요.

2. External Agents 페이지로 가서 Add Agent를 클릭해요.

3. Add Custom Agent를 선택해요. Zed가 agent_servers 항목과 함께 설정 파일을 열어요.

4. 자리 표시자 항목을 Cortex Code 에이전트로 바꿔요. my_connection 대신 Snowflake 연결 이름을 사용해요.

   {
     "agent_servers": {
       "Cortex Code": {
         "type": "custom",
         "command": "cortex",
         "args": ["acp", "serve", "-c", "my_connection"],
         "env": {}
       }
     }
   }
   

5. 설정 파일을 저장해요.

6. Agent 패널에서 새 스레드를 시작하고 외부 에이전트로 Cortex Code를 선택해요.

선택 사항: 에이전트 작업 디렉터리를 설정하려면 args에 Cortex Code CLI -w(--workdir) 플래그를 추가해요. 이것은 Zed 설정이 아니라 Cortex Code 옵션이에요. 위 명령 옵션을 참고하세요.

{
  "agent_servers": {
    "Cortex Code": {
      "type": "custom",
      "command": "cortex",
      "args": ["acp", "serve", "-c", "my_connection", "-w", "/path/to/your/project"],
      "env": {}
    }
  }
}

자세한 내용은 Zed 외부 에이전트 문서를 참고하세요.

Configure JetBrains IDEs

ACP를 지원하는 JetBrains IDE에서 CoCo를 사용하려면 ~/.jetbrains/acp.json에 사용자 정의 에이전트로 추가해요. 시작하기 전에 사전 요구 사항을 완료하고 cortex acp serve -c <connection_name>이 터미널에서 성공적으로 실행되는지 확인하세요.

1. AI Chat 도구 창을 열어요.

2. AI Chat 도구 창 오른쪽 위의 세로 점 3개 버튼을 클릭하고 Add Custom Agent를 선택해요. 이 옵션을 선택하면 ~/.jetbrains/acp.json이 생성되고 편집을 위해 열려요.

3. cortex 실행 파일의 절대 경로를 찾아요.

   which cortex
   

4. acp.json에 agent_servers 아래에 Cortex Code 항목을 채워요. 3단계의 절대 경로와 my_connection 대신 Snowflake 연결 이름을 사용해요.

   {
     "default_mcp_settings": {},
     "agent_servers": {
       "Cortex Code": {
         "command": "/absolute/path/to/cortex",
         "args": ["acp", "serve", "-c", "my_connection"],
         "env": {}
       }
     }
   }
   

5. 파일을 저장해요. IDE는 또한 머신에 이미 설치된 ACP 호환 에이전트를 감지하고 Add to configuration으로 추가하겠다고 제안할 수 있어요.

6. AI Chat에서 Cortex Code를 선택하고 프롬프트를 입력한 뒤 보내요.

선택 사항: 에이전트 작업 디렉터리를 설정하려면 args에 Cortex Code CLI -w(--workdir) 플래그를 추가해요. 이것은 Cortex Code 옵션이며 JetBrains 설정이 아니에요. 위 명령 옵션을 참고하세요.

"args": ["acp", "serve", "-c", "my_connection", "-w", "/path/to/your/project"]

JetBrains는 command 필드에 절대 경로를 요구해요. 에이전트가 시작에 실패하면 which cortex로 경로를 확인하고 acp.json을 업데이트해요.

선택적으로 default_mcp_settings 아래에 use_idea_mcp와 use_custom_mcp를 설정해 IDE MCP 서버를 에이전트에 노출할 수 있어요. 이러한 설정에 대한 자세한 내용은 JetBrains ACP 문서를 참고하세요.

세션 및 대화 기록

ACP 모드에서 시작된 세션은 CoCo CLI에서 만든 세션과 같은 위치에 저장돼요.

~/.snowflake/cortex/conversations/<sessionId>.json
~/.snowflake/cortex/conversations/<sessionId>.history.jsonl

<sessionId>.json 파일은 메타데이터와 대화 기록을 포함한 세션의 완전한 스냅샷을 저장 시점에 포함해요. <sessionId>.history.jsonl 파일은 스냅샷 사이의 증분 내구성을 제공하는 채팅 메시지의 append 전용 로그예요. 두 파일 모두 세션에 속하며 함께 관리돼요.

이는 다음을 의미해요.

• 나중에 CoCo CLI에서 /resume으로, 또는 다른 ACP 클라이언트에서 같은 세션을 열 수 있어요.
• ACP 클라이언트가 loadSession을 요청하면 CoCo는 전체 대화 기록을 ACP SessionUpdate 알림으로 재생해 에디터가 UI를 다시 채울 수 있게 해요.
• /wipe-session 명령은 ACP 클라이언트에서 추가된 메시지를 포함한 전체 세션 추적을 제거해요.

세션 구성 옵션

세션이 생성되거나 로드될 때 CoCo는 ACP 클라이언트가 드롭다운으로 렌더링하는 구성 옵션을 보고해요. 세션 중 언제든지 이 옵션을 변경할 수 있으며, 변경 사항은 이후 프롬프트에 적용돼요.

옵션	값	설명
mode	standard, plan, bypass	도구 승인 동작을 제어해요. standard는 민감한 작업에서 프롬프트를 표시하고, plan은 행동 전에 계획을 만들고, bypass는 모든 도구 호출을 자동 승인해요.
model	CoCo의 지원 모델 목록이 반환하는 모든 모델	세션의 기본 모델을 선택해요. 모델이 설정되지 않으면 CoCo는 자동 선택(자동으로 보고됨)을 사용해요.

주의 bypass 옵션은 관리자가 dangerous mode를 허용한 경우에만 사용할 수 있어요. 관리 환경에서 bypass를 선택하면 오류가 반환되고 세션의 이전 모드가 유지돼요. 관리 설정을 참고하세요.

에디터 도구로 에이전트 확장하기

ACP 클라이언트는 newSession 또는 loadSession 요청에 _meta.clientTools 배열을 전달해 자신의 도구를 CoCo에 노출할 수 있어요. CoCo는 각 항목을 클라이언트 도구로 등록하며, 에이전트가 하나를 호출하면 CoCo가 ACP 연결을 통해 에디터로 콜백하고 에디터가 로컬에서 도구를 실행한 뒤 결과가 에이전트로 반환돼요.

클라이언트 도구 정의는 다음을 포함해요.

필드	필수	설명
name	예	고유 도구 이름. 관례상 이름은 MCP 도구의 예약 접두사인 mcp__로 시작하지 않아야 해요.
description	아니요	에이전트에 표시되는 자연어 설명.
inputSchema	아니요	도구 입력을 설명하는 JSON 스키마. 기본값은 빈 객체 스키마.

클라이언트 도구는 세션별로 등록되며 세션이 끝나거나 ACP 연결이 닫히면 자동으로 제거돼요. 클라이언트 도구의 권한은 활성 세션 모드를 따르며, bypass는 자동 승인하고 standard와 plan은 에디터를 통해 사용자에게 프롬프트를 표시해요.

스트리밍 업데이트

프롬프트가 진행되는 동안 CoCo는 다음 이벤트에 매핑되는 ACP SessionUpdate 알림을 내보내요.

업데이트	발생 시점
agent_message_chunk	에이전트가 응답 텍스트를 스트리밍할 때.
agent_thought_chunk	에이전트가 내부 추론을 스트리밍할 때(생각을 지원하는 모델).
tool_call	에이전트가 도구를 호출할 때. 도구 호출 식별자, 도구 이름에서 파생된 사람이 읽을 수 있는 제목, 종류, 원시 입력을 포함해요.
tool_call_update	도구 호출이 진행, 완료 또는 실패할 때. 파일 편집의 경우 업데이트에 원본 및 새 파일 내용이 있는 diff 콘텐츠 블록이 포함돼요.
plan	플랜 모드가 계획된 단계 목록을 생성하거나 업데이트할 때.
user_message_chunk	loadSession 동안 이전 사용자 메시지가 재생될 때.

파일 편집 도구(예: edit, str_replace_editor, write)는 에디터가 인라인 시각적 diff를 렌더링할 수 있도록 diff 업데이트를 내보내요.

프롬프트 취소하기

ACP 클라이언트는 활성 세션에 대한 cancel 알림을 보내 진행 중인 프롬프트를 취소할 수 있어요. CoCo는 실행 중인 모든 도구 호출을 중단하고 스트리밍을 중지하며 cancelled 중지 이유를 반환해요. 세션 자체는 계속 열려 있으며 다음 프롬프트에 재사용할 수 있어요.

제한 사항

• listSessions 메서드는 현재 unstable_listSessions로 노출되며 ACP 사양이 발전함에 따라 변경될 수 있어요.
• CoCo 슬래시 명령은 아직 ACP 클라이언트에 일급 명령으로 노출되지 않아요. 프롬프트의 일부로 입력해 사용해요(예: /skill list).
• ACP는 별도의 인증 흐름을 제공하지 않아요. CoCo는 시작 시 구성된 Snowflake 연결을 사용해요.

문제 해결

에디터가 에이전트가 즉시 종료되었다고 보고함

터미널에서 같은 명령을 실행해 보세요.

cortex acp serve -c <connection_name>

CoCo가 인증 또는 연결 오류를 출력하면 에디터를 다시 시작하기 전에 기본 연결을 수정하세요. CoCo는 Snowflake 연결을 초기화할 수 없으면 ACP를 말하기 전에 종료돼요.

에이전트가 시작 시 멈추거나 깨진 출력을 생성함

셸 시작 파일(.bashrc, .zshrc 등)이나 래퍼 스크립트가 stdout에 쓰지 않는지 확인하세요. ACP는 stdout을 프로토콜 채널로 사용하며, 잘못된 출력은 ndjson 프레이밍을 깨뜨려요. 진단 출력을 stderr 또는 로그 파일로 리디렉션하세요.

도구 승인이 표시되지 않음

세션 모드를 확인하세요. bypass 모드에서는 도구 호출이 자동 승인되고 프롬프트가 전송되지 않아요. 승인을 복원하려면 에디터의 세션 설정에서 standard 또는 plan으로 전환하세요.

모델 드롭다운이 비어 있음

모델 목록은 세션 생성 시 Snowflake에서 가져와요. 빈 목록은 보통 Snowflake 연결이 유효하지 않거나 계정에 활성화된 모델이 없음을 나타내요. cortex auth status로 확인하고 다시 시도하세요.

더 알아보기

• CoCo CLI
• CoCo CLI MCP support
• CoCo CLI reference