Hermes Agent

Hermes Agent는 터미널에서 실행되는 에이전트로, 사용자 승인을 받은 뒤 파일을 읽고 쓰거나 명령을 실행하고 도구를 호출할 수 있습니다.

이 튜토리얼은 다른 설정 도구 없이 Hermes Agent의 내장 Custom Endpoint를 사용하여 AGTCloud의 Chat Completions 인터페이스에 연동하고 기본 대화를 검증하는 방법을 설명합니다. 파일 작업, 웹 검색, MCP, Skills 등의 확장 기능은 이 튜토리얼의 검증 범위에 포함되지 않습니다.

준비 사항

시작하기 전에 다음 사항을 확인합니다.

Hermes Agent가 지원하는 운영 체제와 터미널 환경을 준비합니다.
AGTCloud에 가입하고 로그인합니다.
API Keys 페이지에서 AGTCloud API Key를 생성합니다.
모델 목록에서 현재 API Key에 표시되며 Chat Completions를 지원하는 모델 ID를 복사합니다.
민감한 코드와 운영 자격 증명이 없는 테스트 디렉터리를 준비합니다.

Hermes Agent 설치

실행 환경에 맞는 공식 설치 방식을 선택합니다. macOS 첫 버전은 Apple Silicon을 지원하며 Intel Mac, Homebrew 및 PyPI 설치는 현재 공식 지원 범위에 포함되지 않습니다.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

설치 후 터미널을 다시 열고 버전과 실행 환경을 확인합니다.

hermes version
hermes doctor

hermes doctor는 설치, 설정 및 일반적인 실행 환경 문제를 검사합니다. 터미널에서 hermes를 찾을 수 없다고 표시되면 터미널을 다시 열고 설치 디렉터리가 PATH에 추가되어 있는지 확인합니다. 다른 플랫폼 제한은 Hermes Agent 공식 플랫폼 지원 설명을 확인합니다.

AGTCloud 설정

Hermes Agent는 모델 공급업체 설정 마법사를 제공합니다. 이미 열려 있는 Hermes 대화 안이 아닌 일반 터미널에서 다음 명령을 실행합니다.

hermes model

Custom Endpoint 선택

Provider 목록에서 Custom endpoint를 선택합니다. 버전에 따라 전체 이름은 Custom endpoint (self-hosted / VLLM / etc.)로 표시될 수 있습니다.

AGTCloud 연결 정보 입력

현재 버전의 마법사에 따라 다음을 순서대로 입력합니다.

Hermes Agent 필드	입력 내용
`Provider Name`(있는 경우)	`AGTCloud`
`API Base URL`	`https://api.agtcloud.cn/v1`
`API Key`	`your-api-key`
`API / Wire Mode`	`Chat Completions` 또는 `chat_completions`
`Model`	`MODEL_ID`
`Context Length`	첫 설정에서는 비워 두고 클라이언트가 자동 감지를 시도하도록 하는 것이 좋습니다

your-api-key를 AGTCloud API Key로, MODEL_ID를 현재 API Key에 표시되는 모델 ID로 교체합니다.

설정 저장

마법사의 요약 내용을 확인한 뒤 저장합니다. 일반 설정은 ~/.hermes/config.yaml에 기록되고 API Key 등의 민감한 값은 Hermes Agent가 ~/.hermes/.env에 저장합니다.

Base URL에는 /v1이 포함되어야 합니다

https://api.agtcloud.cn/v1를 그대로 사용합니다. API Origin만 입력하거나 전체 /v1/chat/completions 요청 주소를 입력하거나 /v1을 다시 추가하지 않습니다.

공식 설정 마법사를 우선 사용합니다

Hermes Agent의 설정 필드는 버전에 따라 바뀔 수 있습니다. hermes model을 사용하면 현재 버전이 올바른 Provider 및 전송 모드를 기록하므로 YAML을 직접 편집할 필요가 없으며 실제 API Key를 공유 설정 예시에 기록하지 않습니다.

설정 확인

마법사를 완료한 뒤 다음 명령으로 현재 설정을 확인할 수 있습니다.

hermes config
hermes config get model
hermes config check

hermes config는 현재 설정 진입점을 열거나 표시합니다.
hermes config get model은 현재 모델 설정을 확인합니다.
hermes config check는 설정 형식과 필수 필드를 검사합니다.

출력을 확인할 때 전체 API Key를 복사하거나 공유하지 않습니다. 설정이 다른 Provider를 가리키면 hermes model을 다시 실행하고 Custom Endpoint 설정을 완료합니다.

실행 및 연결 검증

안전한 테스트 디렉터리로 이동

cd /path/to/safe/test-project

첫 연결은 운영 자격 증명, 고객 자료 또는 미공개 소스 코드가 있는 디렉터리에서 수행하지 않습니다.

Hermes Agent 시작

hermes

hermes chat으로 대화형 세션을 시작할 수도 있습니다.

기본 대화 검증

입력란에 다음을 보냅니다.

AGTCloud 연결 성공이라고만 응답해 주세요. 어떤 도구도 호출하지 마세요.

응답이 정상적으로 수신되면 Base URL, API Key, 모델 및 기본 Chat Completions 연결이 설정된 것입니다. 이 단계에서는 정상적인 API 사용량이 발생합니다.

선택적 도구 호출 검증

선택한 모델이 도구 호출을 지원하면 README.md가 있는 테스트 디렉터리에서 다음을 보낼 수 있습니다.

README.md만 읽고 프로젝트의 용도를 세 가지로 요약해 주세요. 파일을 수정하거나 다른 명령을 실행하지 마세요.

기본 수동 승인을 유지하고 Hermes Agent가 실행하려는 작업을 먼저 확인한 뒤 허용 여부를 결정합니다.

처음 사용할 때 작업 승인을 비활성화하지 않습니다

--yolo를 사용하거나 위험 작업 승인을 비활성화하지 않습니다. Hermes Agent는 명령 실행과 파일 접근이 가능하므로 첫 검증에서는 도구 요청을 개별적으로 확인합니다.

모델 전환

새 모델 추가, Endpoint 수정 또는 API Key 교체가 필요하면 현재 세션을 종료하고 다음을 실행합니다.

hermes model

열려 있는 세션에서는 /model로 이미 설정된 Provider와 모델 사이를 전환할 수 있습니다. /model은 새 Custom Endpoint를 생성하지 않으므로 대상 모델이 아직 설정되지 않았다면 먼저 터미널 명령 hermes model을 사용합니다.

MODEL_ID는 자리표시자입니다. 버전에 따라 바뀔 수 있는 고정 추천 모델에 의존하지 말고 항상 모델 목록에서 현재 API Key에 표시되는 전체 모델 ID를 사용합니다.

자주 묻는 질문

증상	우선 확인할 항목	조치
`hermes` 명령을 찾을 수 없음	설치 결과 및 `PATH`	터미널을 다시 열고 `hermes version`을 실행하며 계속 결과가 없으면 해당 시스템의 공식 설치 명령을 다시 실행합니다
`hermes doctor`가 문제 보고	Python, 시스템 도구 및 설치 디렉터리	진단 결과에 따라 현재 환경을 수정하며 여러 Hermes Agent 설치 출처를 혼용하지 않습니다
`401` 반환	API Key 내용 및 토큰 상태	유효한 API Key를 다시 복사하고 불필요한 공백이 없는지 확인합니다
`403` 반환	토큰 권한, 모델 권한 및 계정 상태	콘솔에서 API Key 상태와 현재 계정의 모델 사용 가능 범위를 확인합니다
`404` 반환	Base URL, 중복 `/v1` 및 모델 ID	`https://api.agtcloud.cn/v1`를 사용하고 전체 Endpoint를 입력하지 않으며 전체 모델 ID를 다시 복사합니다
모델 사용 불가	현재 Key에 표시되는 모델 및 프로토콜 지원	현재 API Key에 표시되며 Chat Completions를 지원하는 모델을 선택합니다
다른 Provider를 계속 사용함	`hermes model`의 현재 선택 및 저장 결과	마법사를 다시 실행하여 Custom Endpoint를 선택하고 `hermes config check`로 설정을 검사합니다
대화는 정상이지만 도구 실패	모델의 도구 호출 기능 및 응답 형식	도구 호출 지원 모델로 바꾸고 복잡한 도구를 비활성화한 뒤 읽기 전용 작업 하나만 검증합니다
컨텍스트 길이 감지 실패	모델 메타데이터 및 수동 입력 값	`hermes model`을 다시 실행하며 모델의 실제 제한을 파악한 경우에만 컨텍스트 길이를 직접 입력합니다
확장 도구의 자격 증명 누락	보조 도구의 독립된 서비스 설정	추가 서비스와 자격 증명이 필요할 수 있으며 AGTCloud 주 대화 모델 Key 설정 범위에는 포함되지 않습니다

원인을 찾기 어려우면 hermes doctor와 hermes config check를 실행하고 요청 시각, API Base URL, 모델 ID, HTTP 상태 및 민감 정보를 제거한 오류 내용을 기록한 뒤 오류 및 문제 해결을 확인합니다. 전체 API Key를 제출하지 않습니다.

보안 권장 사항

API Key를 프로젝트 파일, Git 저장소, 명령 기록, 스크린샷, 로그 또는 공유 설정에 기록하지 않습니다.
처음 사용할 때는 안전한 테스트 디렉터리에서 파일, 명령 및 네트워크 접근 요청을 개별적으로 검사합니다.
--yolo 또는 설정 항목으로 위험 작업 확인을 비활성화하지 않습니다.
신뢰할 수 없는 코드를 처리할 때 Docker 등의 격리 환경으로 위험을 줄일 수 있지만 마운트 디렉터리와 자격 증명은 여전히 검사해야 합니다.
API Key 유출이 의심되면 즉시 콘솔에서 비활성화하거나 삭제하고 새 Key를 생성합니다.