Provider 추가

기준일: 2026-08-02
난이도: 중급
공식 기준: Adding Providers

개요

Hermes는 커스텀 provider 경로로 이미 모든 OpenAI-compatible 엔드포인트와 대화할 수 있습니다. 다음 중 어느 것도 필요 없다면 빌트인 provider를 추가하지 마세요.

• provider 고유 인증이나 토큰 갱신
• 정제된 모델 카탈로그
• setup / hermes model 메뉴 항목
• provider:model 문법을 위한 provider alias
• 어댑터가 필요한 non-OpenAI API 형태

그냥 "다른 OpenAI-compatible base URL과 API 키"일 뿐이라면, 이름을 가진 커스텀 provider만으로 충분할 수 있습니다.

핵심 개념

경로	언제
OpenAI-compatible	chat completions 호환
Native	독자 프로토콜
Canonical id	코드/설정 단일 ID
Auxiliary	요약·비전 등 보조 호출

구현 가이드

멘탈 모델

빌트인 provider는 다음 계층에 걸쳐 정렬되어야 합니다.

1. hermes_cli/auth.py — 자격 증명을 어떻게 찾을지 결정한다.
2. hermes_cli/runtime_provider.py — 이를 런타임 데이터(provider, api_mode, base_url, api_key, source)로 변환한다.
3. run_agent.py — api_mode로 요청을 어떻게 만들고 보낼지 결정한다.
4. hermes_cli/models.py와 hermes_cli/main.py — provider가 CLI에 노출되게 한다(hermes_cli/setup.py는 main.py에 자동으로 위임하므로 별도 변경이 필요 없다).
5. agent/auxiliary_client.py와 agent/model_metadata.py — 보조 작업과 토큰 예산 계산이 계속 동작하게 한다.

핵심 추상화는 api_mode입니다. 대부분의 provider는 chat_completions를 쓰고, Codex는 codex_responses, Anthropic은 anthropic_messages를 씁니다. 새로운 non-OpenAI 프로토콜은 보통 새 어댑터와 새 api_mode 분기가 필요하다는 뜻입니다.

구현 경로 먼저 선택

Path A — OpenAI-compatible provider

provider가 표준 chat-completions 스타일 요청을 받아들일 때 씁니다. 일반적인 작업: auth 메타데이터 추가, 모델 카탈로그·alias 추가, 런타임 resolution 추가, CLI 메뉴 배선 추가, aux 모델 기본값 추가, 테스트·유저 문서 추가. 보통 새 어댑터나 새 api_mode는 필요 없습니다.

Path B — Native provider

provider가 OpenAI chat completions처럼 동작하지 않을 때 씁니다. 현재 저장소의 예: codex_responses, anthropic_messages. 이 경로는 Path A의 모든 작업에 더해 agent/의 provider 어댑터, 요청 구성·디스패치·usage 추출·인터럽트 처리·응답 정규화를 위한 run_agent.py 분기, 어댑터 테스트가 추가로 필요합니다.

파일 체크리스트

모든 빌트인 provider에 공통으로 필요

1. hermes_cli/auth.py
2. hermes_cli/models.py
3. hermes_cli/runtime_provider.py
4. hermes_cli/main.py
5. agent/auxiliary_client.py
6. agent/model_metadata.py
7. 테스트
8. website/docs/ 아래 사용자 문서

Tip: hermes_cli/setup.py는 변경할 필요가 없습니다. setup 마법사는 main.py의 select_provider_and_model()에 provider·모델 선택을 위임하므로, 거기에 추가한 provider는 hermes setup에서도 자동으로 쓸 수 있습니다.

native / non-OpenAI provider에 추가로 필요

10. agent/<provider>_adapter.py
11. run_agent.py
12. provider SDK가 필요하면 pyproject.toml

빠른 경로: 단순 API 키 provider

provider가 단일 API 키로 인증하는 OpenAI-compatible 엔드포인트일 뿐이라면 auth.py, runtime_provider.py, main.py나 그 밖의 전체 체크리스트 파일을 건드릴 필요가 없습니다.

필요한 건 다음뿐입니다.

1. plugins/model-providers/<your-provider>/ 아래 플러그인 디렉터리
   • __init__.py — 모듈 레벨에서 register_provider(profile)를 호출
   • plugin.yaml — 매니페스트(name, kind: model-provider, version, description)
2. 이게 전부입니다. Provider 플러그인은 get_provider_profile()이나 list_providers()가 처음 호출될 때 자동으로 로드됩니다 — 이 저장소에 번들된 플러그인과 $HERMES_HOME/plugins/model-providers/의 사용자 플러그인 모두 대상입니다.

플러그인이 register_provider()를 호출하면 다음이 자동으로 연결됩니다.

1. auth.py의 PROVIDER_REGISTRY 항목(자격 증명 resolution, env-var 조회)
2. api_mode가 chat_completions로 설정
3. 설정 또는 선언된 env var에서 가져오는 base_url
4. 우선순위 순으로 확인되는 env_vars
5. provider용 fallback_models 목록 등록
6. --provider CLI 플래그가 해당 provider id를 인식
7. hermes model 메뉴에 provider 포함
8. hermes setup 마법사가 main.py에 자동으로 위임
9. provider:model alias 문법 동작
10. 런타임 resolver가 올바른 base_url·api_key 반환
11. --provider <name> CLI 플래그가 해당 provider id 인식
12. fallback 모델 활성화가 해당 provider로 매끄럽게 전환

$HERMES_HOME/plugins/model-providers/<name>/의 사용자 플러그인은 같은 이름의 번들 플러그인을 덮어씁니다(register_provider()의 last-writer-wins) — 그래서 서드파티가 저장소를 건드리지 않고도 빌트인 프로필을 몽키패치하거나 교체할 수 있습니다.

템플릿은 plugins/model-providers/nvidia/나 plugins/model-providers/gmi/를 참고하고, 필드 레퍼런스·훅 관용구·엔드투엔드 예제는 Model Provider Plugin 가이드를 참고하세요.

전체 경로: OAuth·복잡 provider

다음 중 하나라도 필요하면 전체 체크리스트를 씁니다.

• OAuth나 토큰 갱신(Nous Portal, Codex, Qwen Portal, Copilot)
• 새 어댑터가 필요한 non-OpenAI API 형태(Anthropic Messages, Codex Responses)
• 커스텀 엔드포인트 탐지나 멀티 리전 probing(z.ai, Kimi)
• 정제된 정적 모델 카탈로그나 실시간 /models fetch
• provider별 맞춤 인증 흐름을 가진 hermes model 메뉴 항목

Step 1: 단일 canonical provider id 선정

저장소 예: openai-codex, kimi-coding, minimax-cn. 같은 id가 다음 모든 곳에 등장해야 합니다: hermes_cli/auth.py의 PROVIDER_REGISTRY, hermes_cli/models.py의 _PROVIDER_LABELS, hermes_cli/auth.py·hermes_cli/models.py 양쪽의 _PROVIDER_ALIASES, hermes_cli/main.py의 CLI --provider 선택지, setup/모델 선택 분기, 보조 모델 기본값, 테스트. id가 파일마다 다르면 provider가 절반만 배선된 것처럼 동작합니다 — auth는 되는데 /model·setup·런타임 resolution에서는 조용히 빠집니다.

Step 2: hermes_cli/auth.py에 auth 메타데이터 추가

API 키 provider라면 PROVIDER_REGISTRY에 id, name, auth_type="api_key", inference_base_url, api_key_env_vars, 선택적으로 base_url_env_var를 담은 ProviderConfig 항목을 추가합니다. _PROVIDER_ALIASES에도 alias를 추가합니다.

템플릿: 단순 API 키 경로는 Z.AI·MiniMax, 엔드포인트 탐지가 있는 API 키 경로는 Kimi·Z.AI, native 토큰 resolution은 Anthropic, OAuth/auth-store 경로는 Nous·OpenAI Codex를 참고합니다.

여기서 답해야 할 질문: Hermes가 확인할 env var와 그 우선순위는? base URL 오버라이드가 필요한가? 엔드포인트 probing이나 토큰 갱신이 필요한가? 자격 증명이 없을 때 auth 에러 메시지는 무엇이어야 하는가? "API 키 조회" 이상이 필요하다면 무관한 분기에 로직을 억지로 끼워 넣지 말고 전용 자격 증명 resolver를 추가하세요.

Step 3: hermes_cli/models.py에 모델 카탈로그·alias 추가

메뉴와 provider:model 문법에서 동작하도록 provider 카탈로그를 갱신합니다. 일반적인 수정 대상: _PROVIDER_MODELS, _PROVIDER_LABELS, _PROVIDER_ALIASES, list_available_providers() 안의 표시 순서, 실시간 /models fetch를 지원하면 provider_model_ids(). provider가 실시간 모델 목록을 제공하면 그것을 우선하고 _PROVIDER_MODELS는 정적 폴백으로 남겨둡니다.

이 파일 덕분에 다음과 같은 입력이 동작합니다.

anthropic:claude-sonnet-4-6
kimi:model-name

여기 alias가 빠지면 인증은 되지만 /model 파싱에서 실패할 수 있습니다.

Step 4: hermes_cli/runtime_provider.py에서 런타임 데이터 resolve

resolve_runtime_provider()는 CLI, gateway, cron, ACP, helper client가 공유하는 경로입니다. 최소한 다음을 반환하는 분기를 추가합니다.

{
    "provider": "your-provider",
    "api_mode": "chat_completions",  # or your native mode
    "base_url": "https://...",
    "api_key": "...",
    "source": "env|portal|auth-store|explicit",
    "requested_provider": requested_provider,
}

provider가 OpenAI-compatible이면 api_mode는 보통 chat_completions로 둡니다. API 키 우선순위에 주의하세요 — Hermes에는 이미 OpenRouter 키가 무관한 엔드포인트로 새는 것을 막는 로직이 있습니다. 새 provider도 어떤 키가 어떤 base URL로 가는지 똑같이 명확해야 합니다.

Step 5: hermes_cli/main.py에서 CLI 배선

provider는 대화형 hermes model 흐름에 나타나야 비로소 발견 가능해집니다. hermes_cli/main.py에서 다음을 갱신합니다: provider_labels 딕셔너리, select_provider_and_model()의 providers 목록, provider 디스패치(if selected_provider == ...), --provider 인자 선택지, 해당 provider가 지원하면 login/logout 선택지, _model_flow_<provider>() 함수(또는 맞는다면 _model_flow_api_key_provider() 재사용).

Tip: hermes_cli/setup.py는 변경이 필요 없습니다 — main.py의 select_provider_and_model()을 호출하므로 새 provider는 hermes model과 hermes setup 양쪽에 자동으로 나타납니다.

Step 6: 보조 호출 유지

agent/auxiliary_client.py — 직접 API 키 provider라면 _API_KEY_PROVIDER_AUX_MODELS에 저렴하고 빠른 기본 aux 모델을 추가합니다. 보조 작업에는 비전 요약, 웹 추출 요약, 컨텍스트 압축 요약, 세션 검색 요약, 메모리 플러시 등이 있습니다. 적절한 aux 기본값이 없으면 부수 작업이 나쁘게 폴백하거나 예상치 못하게 비싼 메인 모델을 쓸 수 있습니다.

agent/model_metadata.py — provider 모델들의 context length를 추가해 토큰 예산 계산, 압축 임계값, 한도가 올바르게 유지되게 합니다.

Step 7: provider가 native라면 어댑터와 run_agent.py 지원 추가

provider가 순수 chat completions가 아니라면 provider 고유 로직을 agent/<provider>_adapter.py에 격리하세요. run_agent.py는 오케스트레이션에 집중해야 합니다 — 어댑터 헬퍼를 호출해야지, provider 페이로드를 파일 전체에 걸쳐 직접 조립해서는 안 됩니다.

새 어댑터 파일의 전형적인 책임: SDK·HTTP 클라이언트 구성, 토큰 resolve, OpenAI 스타일 대화 메시지를 provider 요청 형식으로 변환, 필요하면 도구 스키마 변환, provider 응답을 run_agent.py가 기대하는 형태로 정규화, usage·finish-reason 데이터 추출.

**run_agent.py**에서는 api_mode를 검색해 모든 분기점을 감사합니다. 최소한 다음을 확인하세요: __init__이 새 api_mode를 선택하는지, provider에 맞게 클라이언트가 구성되는지, _build_api_kwargs()가 요청을 올바르게 포맷하는지, _interruptible_api_call()이 올바른 클라이언트 호출로 디스패치하는지, 인터럽트·클라이언트 재구성 경로가 동작하는지, 응답 검증이 provider 형태를 받아들이는지, finish-reason·토큰 usage 추출이 맞는지, fallback 모델 활성화가 새 provider로 매끄럽게 전환되는지, 요약 생성·메모리 플러시 경로가 계속 동작하는지. run_agent.py에서 self.client.도 검색하세요 — 표준 OpenAI 클라이언트가 존재한다고 가정하는 코드 경로는 native provider가 다른 클라이언트 객체를 쓰거나 self.client = None일 때 깨질 수 있습니다.

프롬프트 캐싱과 provider별 요청 필드: 프롬프트 캐싱과 provider 고유 옵션은 리그레션이 나기 쉽습니다. 이미 저장소에 있는 예: Anthropic은 native 프롬프트 캐싱 경로를 갖고, OpenRouter는 provider-routing 필드를 받습니다. 모든 provider가 모든 요청 옵션을 받아야 하는 건 아닙니다. native provider를 추가할 때는 Hermes가 그 provider가 실제로 이해하는 필드만 보내는지 다시 확인하세요.

Step 8: 테스트

최소한 provider 배선을 지키는 테스트는 건드립니다. 흔한 위치:

• tests/hermes_cli/test_runtime_provider_resolution.py
• tests/cli/test_cli_provider_resolution.py
• tests/hermes_cli/test_model_switch_custom_providers.py(그리고 인접한 tests/hermes_cli/test_model_switch_*.py)
• tests/hermes_cli/test_setup_model_provider.py
• tests/run_agent/test_provider_parity.py
• tests/run_agent/test_run_agent.py
• native provider라면 tests/test_<provider>_adapter.py

핵심은 auth resolution, CLI 메뉴·provider 선택, 런타임 provider resolution, 에이전트 실행 경로, provider:model 파싱, 어댑터별 메시지 변환을 커버하는 것입니다.

source venv/bin/activate
python -m pytest tests/hermes_cli/test_runtime_provider_resolution.py tests/cli/test_cli_provider_resolution.py tests/hermes_cli/test_setup_model_provider.py tests/run_agent/test_provider_parity.py -n0 -q

더 깊은 변경이라면 푸시 전에 전체 스위트를 돌립니다.

source venv/bin/activate
python -m pytest tests/ -n0 -q

(각 파일을 별도 서브프로세스에서 돌리는 scripts/run_tests.sh를 대신 써도 됩니다.)

Step 9: 실 사용 검증

테스트 다음에는 실제 스모크 테스트를 돌립니다.

source venv/bin/activate
python -m hermes_cli.main chat -q "Say hello" --provider your-provider --model your-model

메뉴를 바꿨다면 대화형 흐름도 확인합니다.

source venv/bin/activate
python -m hermes_cli.main model
python -m hermes_cli.main setup

native provider라면 텍스트 응답뿐 아니라 도구 호출도 최소 한 번 검증하세요.

Step 10: 사용자 문서 갱신

provider가 정식 옵션으로 나갈 예정이면 사용자 문서도 갱신합니다.

• website/docs/getting-started/quickstart.md
• website/docs/user-guide/configuration.md
• website/docs/reference/environment-variables.md

배선을 완벽히 해도 사용자가 필요한 env var나 설정 흐름을 찾지 못하면 소용없습니다.

OpenAI-compatible provider 체크리스트

표준 chat completions provider일 때 씁니다.

• hermes_cli/auth.py에 ProviderConfig 추가
• hermes_cli/auth.py·hermes_cli/models.py에 alias 추가
• hermes_cli/models.py에 모델 카탈로그 추가
• hermes_cli/runtime_provider.py에 런타임 분기 추가
• hermes_cli/main.py에 CLI 배선 추가(setup.py는 자동 상속)
• agent/auxiliary_client.py에 aux 모델 추가
• agent/model_metadata.py에 context length 추가
• 런타임/CLI 테스트 갱신
• 사용자 문서 갱신

Native provider 체크리스트

새 프로토콜 경로가 필요할 때 씁니다.

• OpenAI-compatible 체크리스트 전부
• agent/<provider>_adapter.py에 어댑터 추가
• run_agent.py에 새 api_mode 지원 추가
• 인터럽트·재구성 경로 동작
• usage·finish-reason 추출 동작
• fallback 경로 동작
• 어댑터 테스트 추가
• 실 사용 스모크 테스트 통과

흔한 실수

1. auth에는 추가했지만 모델 파싱에는 추가하지 않음 — 자격 증명은 정상 resolve되지만 /model과 provider:model 입력이 실패합니다.

2. config["model"]이 문자열일 수도, dict일 수도 있음을 잊음 — provider 선택 코드 상당수가 두 형태를 모두 정규화해야 합니다.

3. 빌트인 provider가 필요하다고 가정 — 서비스가 그냥 OpenAI-compatible이라면 커스텀 provider만으로 유지보수 부담 없이 이미 해결될 수 있습니다.

4. 보조 경로를 잊음 — 메인 채팅 경로는 동작하는데 aux 라우팅을 갱신하지 않아 요약·메모리 플러시·비전 헬퍼가 실패할 수 있습니다.

5. run_agent.py에 숨은 native-provider 분기 — api_mode와 self.client.를 검색하세요. 뻔해 보이는 요청 경로가 유일한 경로라고 가정하지 마세요.

6. OpenRouter 전용 옵션을 다른 provider에 전송 — provider-routing 같은 필드는 그것을 지원하는 provider에만 보내야 합니다.

7. hermes model은 갱신했지만 hermes setup은 갱신하지 않음 — 두 흐름 모두 provider를 알아야 합니다.

구현 중 검색하기 좋은 대상

provider가 어디에 닿아 있는지 찾을 때는 다음 심볼을 검색하세요: PROVIDER_REGISTRY, _PROVIDER_ALIASES, _PROVIDER_MODELS, resolve_runtime_provider, _model_flow_, select_provider_and_model, api_mode, _API_KEY_PROVIDER_AUX_MODELS, self.client.

관련 문서

• Provider Runtime Resolution
• Architecture
• Contributing

체크리스트

• 공식 원문 Adding Providers과 대조했다
• 관련 코드·설정·권한을 로컬에서 확인했다
• 보안·opt-in·allowlist 정책을 지켰다
• 스모크 테스트 또는 단계 검증을 수행했다

다음 단계

• 공식 문서: Adding Providers
• Hermes Agent 소개
• 트러블슈팅