ACP 에디터 통합

Hermes Agent는 ACP 서버로 실행할 수 있습니다. ACP 호환 에디터는 stdio를 통해 Hermes와 통신하고 다음 항목을 표시할 수 있습니다.

채팅 메시지
도구 활동
파일 diff
터미널 명령
승인 프롬프트
스트리밍되는 thinking / 응답 chunk

Hermes를 standalone CLI나 messaging bot이 아니라 에디터에 내장된 coding agent처럼 사용하고 싶다면 ACP가 잘 맞습니다.

ACP 모드에서 Hermes가 노출하는 것

Hermes는 에디터 workflow에 맞게 구성된 hermes-acp toolset으로 실행됩니다. 이 toolset에는 다음이 포함됩니다.

파일 도구: read_file, write_file, patch, search_files
터미널 도구: terminal, process
웹/브라우저 도구
memory, todo, 세션 검색
skills
execute_code 및 delegate_task
vision

messaging delivery나 cronjob 관리처럼 일반적인 에디터 UX에 맞지 않는 기능은 의도적으로 제외됩니다.

설치

Hermes를 일반적으로 설치한 뒤 ACP extra를 추가합니다.

pip install -e '.[acp]'

이 명령은 agent-client-protocol dependency를 설치하고 다음 entry point를 활성화합니다.

hermes acp
hermes-acp
python -m acp_adapter

Zed 레지스트리 설치의 경우, Zed는 공식 ACP Registry entry를 통해 Hermes를 실행합니다. 이 entry는 다음을 실행하는 uvx distribution을 사용합니다.

uvx --from 'hermes-agent[acp]==<version>' hermes-acp

레지스트리 설치 경로를 사용하기 전에 uv가 PATH에서 사용 가능한지 확인하세요.

ACP 서버 시작

다음 중 어느 명령을 사용해도 Hermes가 ACP 모드로 시작됩니다.

hermes acp

hermes-acp

python -m acp_adapter

Hermes는 로그를 stderr로 보냅니다. stdout은 ACP JSON-RPC traffic 전용으로 남겨 둡니다.

non-interactive check에는 다음을 사용합니다.

hermes acp --version
hermes acp --check

브라우저 도구(optional)

브라우저 도구(browser_navigate, browser_click 등)는 agent-browser npm package와 Chromium에 의존합니다. 이 둘은 Python wheel에 포함되어 있지 않습니다. 다음 명령으로 설치합니다.

hermes acp --setup-browser           # interactive (prompts before ~400 MB download)
hermes acp --setup-browser --yes     # accept the download non-interactively

이는 standalone 명령입니다. Zed 레지스트리의 terminal-auth flow(hermes acp --setup)도 model 선택 후 후속 질문으로 브라우저 bootstrap을 제공하므로, 대부분의 사용자는 --setup-browser를 직접 실행할 필요가 없습니다.

이 bootstrap이 하는 일:

Node.js 22 LTS가 없으면 ~/.hermes/node/에 설치합니다.
해당 prefix에 npm install -g agent-browser @askjo/camofox-browser를 실행합니다. npm의 --prefix가 Hermes가 관리하는 user-writable Node를 가리키므로 sudo가 필요 없습니다.
Playwright Chromium을 설치하거나, 사용 가능한 system Chrome/Chromium을 감지하면 그것을 사용합니다.

bootstrap은 idempotent합니다. 다시 실행해도 이미 끝난 작업은 건너뛰므로 빠르게 완료됩니다.

에디터 설정

VS Code

ACP Client extension을 설치합니다.

연결 방법:

Activity Bar에서 ACP Client panel을 엽니다.
built-in agent list에서 Hermes Agent를 선택합니다.
연결한 뒤 chat을 시작합니다.

Hermes를 수동으로 정의하려면 VS Code settings의 acp.agents 아래에 추가합니다.

{
  "acp.agents": {
    "Hermes Agent": {
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

Zed

Zed v0.221.x 이상은 공식 ACP Registry를 통해 external agent를 설치합니다.

Agent Panel을 엽니다.
Add Agent를 클릭하거나 zed: acp registry command를 실행합니다.
Hermes Agent를 검색합니다.
설치한 뒤 새 Hermes external-agent thread를 시작합니다.

필수 조건:

먼저 hermes model로 Hermes provider credential을 설정하거나, ~/.hermes/.env / ~/.hermes/config.yaml에 설정합니다.
레지스트리 launcher가 uvx --from 'hermes-agent[acp]==<version>' hermes-acp를 실행할 수 있도록 uv를 설치합니다.

레지스트리 entry가 제공되기 전 local development에서는 Zed settings에 custom agent server를 설정합니다.

{
  "agent_servers": {
    "hermes-agent": {
      "type": "custom",
      "command": "hermes",
      "args": ["acp"]
    }
  }
}

JetBrains

ACP 호환 plugin을 사용하고 다음 경로를 가리키게 합니다.

/path/to/hermes-agent/acp_registry

레지스트리 manifest

Hermes의 공식 ACP Registry metadata source copy는 다음 위치에 있습니다.

acp_registry/agent.json
acp_registry/icon.svg

upstream registry PR은 이 파일들을 agentclientprotocol/registry repository의 top-level hermes-agent/ directory로 복사합니다.

레지스트리 entry는 hermes-agent PyPI release를 직접 가리키는 uvx distribution을 사용합니다.

uvx --from 'hermes-agent[acp]==<version>' hermes-acp

레지스트리 CI는 pinned version이 PyPI에 존재하는지 검증합니다. 따라서 manifest의 version과 uvx package pin은 항상 pyproject.toml과 일치해야 합니다. scripts/release.py가 이를 자동으로 lockstep에 맞춥니다.

configuration 및 credential

ACP 모드는 CLI와 같은 Hermes configuration을 사용합니다.

~/.hermes/.env
~/.hermes/config.yaml
~/.hermes/skills/
~/.hermes/state.db

provider resolution은 Hermes의 일반 runtime resolver를 사용합니다. 따라서 ACP는 현재 설정된 provider와 credential을 그대로 상속합니다. Hermes는 첫 실행 레지스트리 client를 위해 terminal auth method(--setup)도 제공합니다. 이 flow는 Hermes의 interactive model/provider setup을 엽니다.

세션 동작

ACP 세션은 서버가 실행 중인 동안 ACP adapter의 in-memory session manager가 추적합니다.

각 세션은 다음을 저장합니다.

세션 ID
작업 디렉터리
선택된 모델
현재 대화 기록
cancel event

기저의 AIAgent는 여전히 Hermes의 일반 persistence/logging path를 사용합니다. 다만 ACP의 list/load/resume/fork는 현재 실행 중인 ACP 서버 프로세스 범위에 한정됩니다.

작업 디렉터리 동작

ACP 세션은 에디터의 cwd를 Hermes task ID에 bind합니다. 따라서 파일 및 터미널 도구는 서버 프로세스 cwd가 아니라 에디터 workspace 기준으로 실행됩니다.

승인

위험한 terminal command는 에디터로 approval prompt를 다시 보낼 수 있습니다. ACP approval option은 CLI flow보다 단순합니다.

allow once
allow always
deny

timeout이나 error가 발생하면 approval bridge는 요청을 deny합니다.

문제 해결

ACP agent가 에디터에 나타나지 않음

다음을 확인하세요.

Zed에서는 zed: acp registry로 ACP Registry를 열고 Hermes Agent를 검색합니다.
manual/local development에서는 custom agent_servers command가 hermes acp를 가리키는지 확인합니다.
Hermes가 설치되어 있고 PATH에 있는지 확인합니다.
ACP extra가 설치되어 있는지 확인합니다. (pip install -e '.[acp]')
공식 Zed registry entry로 시작하는 경우 uv가 설치되어 있는지 확인합니다.

ACP가 시작되지만 즉시 오류가 남

다음 check를 시도하세요.

hermes acp --version
hermes acp --check
hermes doctor
hermes status

credential 누락

ACP 모드는 Hermes의 기존 provider setup을 사용합니다. credential은 다음 명령으로 설정합니다.

hermes model

또는 ~/.hermes/.env를 수정합니다. 레지스트리 client도 Hermes의 terminal auth flow를 trigger할 수 있으며, 이 flow는 같은 interactive provider/model setup을 실행합니다.

Zed registry launcher가 uv를 찾지 못함

공식 uv installation docs에 따라 uv를 설치한 뒤, Zed에서 Hermes Agent thread를 다시 시도하세요.

ACP 모드에서 Hermes가 노출하는 것​

설치​

ACP 서버 시작​

브라우저 도구(optional)​

에디터 설정​

VS Code​

Zed​

JetBrains​

레지스트리 manifest​

configuration 및 credential​

세션 동작​

작업 디렉터리 동작​

승인​

문제 해결​

ACP agent가 에디터에 나타나지 않음​

ACP가 시작되지만 즉시 오류가 남​

credential 누락​

Zed registry launcher가 uv를 찾지 못함​

같이 보기​