Provider 추가

기준일: 2026-07-26
난이도: 중급
공식 기준: Adding Providers

개요

Hermes에 새 inference provider를 추가하는 auth·런타임·CLI·테스트·문서 절차입니다.

핵심 개념

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

상세

멘탈 모델

원문 절: The mental model

hermes_cli/auth.py decides how credentials are found.
hermes_cli/runtime_provider.py turns that into runtime data:
run_agent.py uses api_mode to decide how requests are built and sent.
hermes_cli/models.py and hermes_cli/main.py make the provider show up in the CLI. (hermes_cli/setup.py delegate...
agent/auxiliary_client.py and agent/model_metadata.py keep side tasks and token budgeting working.

구현 경로 먼저 선택

원문 절: Choose the implementation path first

Path A — OpenAI-compatible provider — 공식 하위 절. 구현·설정 세부 원문 참조.
Path B — Native provider — 공식 하위 절. 구현·설정 세부 원문 참조.

파일 체크리스트

원문 절: File checklist

Required for every built-in provider — 공식 하위 절. 구현·설정 세부 원문 참조.
Additional for native / non-OpenAI providers — 공식 하위 절. 구현·설정 세부 원문 참조.
hermes_cli/auth.py
hermes_cli/models.py
hermes_cli/runtime_provider.py
hermes_cli/main.py

빠른 경로: 단순 API 키 provider

원문 절: Fast path: Simple API-key providers

A plugin directory under plugins/model-providers/<your-provider>/ containing:
That's it. Provider plugins auto-load the first time anything calls get_provider_profile() or list_providers() — ...
PROVIDER_REGISTRY entry in auth.py (credential resolution, env-var lookup)
api_mode set to chat_completions
base_url sourced from the config or the declared env var
env_vars checked in priority order for the API key

전체 경로: OAuth·복잡 provider

원문 절: Full path: OAuth and complex providers

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Step 1: Pick one canonical provider id

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Step 2: Add auth metadata in `hermes_cli/auth.py`

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Step 3: Add model catalog and aliases in `hermes_cli/models.py`

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

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

Step 4: Resolve runtime data in `hermes_cli/runtime_provider.py`

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

{
    "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,
}

Step 5: Wire the CLI in `hermes_cli/main.py`

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Step 6: Keep auxiliary calls working

agent/auxiliary_client.py — 공식 하위 절. 구현·설정 세부 원문 참조.
agent/model_metadata.py — 공식 하위 절. 구현·설정 세부 원문 참조.

Step 7: If the provider is native, add an adapter and `run_agent.py` support

New adapter file — 공식 하위 절. 구현·설정 세부 원문 참조.
run_agent.py — 공식 하위 절. 구현·설정 세부 원문 참조.
Prompt caching and provider-specific request fields — 공식 하위 절. 구현·설정 세부 원문 참조.

Step 8: Tests

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

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

Step 9: Live verification

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

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

Step 10: Update user-facing docs

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

OpenAI-compatible provider checklist

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Native provider checklist

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Common pitfalls

1. Adding the provider to auth but not to model parsing — 공식 하위 절. 구현·설정 세부 원문 참조.
2. Forgetting that config["model"] can be a string or a dict — 공식 하위 절. 구현·설정 세부 원문 참조.
3. Assuming a built-in provider is required — 공식 하위 절. 구현·설정 세부 원문 참조.
4. Forgetting auxiliary paths — 공식 하위 절. 구현·설정 세부 원문 참조.
5. Native-provider branches hiding in run_agent.py — 공식 하위 절. 구현·설정 세부 원문 참조.
6. Sending OpenRouter-only knobs to other providers — 공식 하위 절. 구현·설정 세부 원문 참조.

Good search targets while implementing

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

체크리스트

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

다음 단계

기준일: 2026-07-26 — 공식 문서 동기화 코퍼스

Provider 추가

기준일: 2026-07-26
난이도: 중급
공식 기준: Adding Providers

개요

Hermes에 새 inference provider를 추가하는 auth·런타임·CLI·테스트·문서 절차입니다.

핵심 개념

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

상세

멘탈 모델

원문 절: The mental model

hermes_cli/auth.py decides how credentials are found.
hermes_cli/runtime_provider.py turns that into runtime data:
run_agent.py uses api_mode to decide how requests are built and sent.
hermes_cli/models.py and hermes_cli/main.py make the provider show up in the CLI. (hermes_cli/setup.py delegate...
agent/auxiliary_client.py and agent/model_metadata.py keep side tasks and token budgeting working.

구현 경로 먼저 선택

원문 절: Choose the implementation path first

Path A — OpenAI-compatible provider — 공식 하위 절. 구현·설정 세부 원문 참조.
Path B — Native provider — 공식 하위 절. 구현·설정 세부 원문 참조.

파일 체크리스트

원문 절: File checklist

Required for every built-in provider — 공식 하위 절. 구현·설정 세부 원문 참조.
Additional for native / non-OpenAI providers — 공식 하위 절. 구현·설정 세부 원문 참조.
hermes_cli/auth.py
hermes_cli/models.py
hermes_cli/runtime_provider.py
hermes_cli/main.py

빠른 경로: 단순 API 키 provider

원문 절: Fast path: Simple API-key providers

A plugin directory under plugins/model-providers/<your-provider>/ containing:
That's it. Provider plugins auto-load the first time anything calls get_provider_profile() or list_providers() — ...
PROVIDER_REGISTRY entry in auth.py (credential resolution, env-var lookup)
api_mode set to chat_completions
base_url sourced from the config or the declared env var
env_vars checked in priority order for the API key

전체 경로: OAuth·복잡 provider

원문 절: Full path: OAuth and complex providers

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Step 1: Pick one canonical provider id

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Step 2: Add auth metadata in `hermes_cli/auth.py`

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Step 3: Add model catalog and aliases in `hermes_cli/models.py`

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

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

Step 4: Resolve runtime data in `hermes_cli/runtime_provider.py`

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

{
    "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,
}

Step 5: Wire the CLI in `hermes_cli/main.py`

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Step 6: Keep auxiliary calls working

agent/auxiliary_client.py — 공식 하위 절. 구현·설정 세부 원문 참조.
agent/model_metadata.py — 공식 하위 절. 구현·설정 세부 원문 참조.

Step 7: If the provider is native, add an adapter and `run_agent.py` support

New adapter file — 공식 하위 절. 구현·설정 세부 원문 참조.
run_agent.py — 공식 하위 절. 구현·설정 세부 원문 참조.
Prompt caching and provider-specific request fields — 공식 하위 절. 구현·설정 세부 원문 참조.

Step 8: Tests

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

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

Step 9: Live verification

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

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

Step 10: Update user-facing docs

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

OpenAI-compatible provider checklist

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Native provider checklist

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

Common pitfalls

1. Adding the provider to auth but not to model parsing — 공식 하위 절. 구현·설정 세부 원문 참조.
2. Forgetting that config["model"] can be a string or a dict — 공식 하위 절. 구현·설정 세부 원문 참조.
3. Assuming a built-in provider is required — 공식 하위 절. 구현·설정 세부 원문 참조.
4. Forgetting auxiliary paths — 공식 하위 절. 구현·설정 세부 원문 참조.
5. Native-provider branches hiding in run_agent.py — 공식 하위 절. 구현·설정 세부 원문 참조.
6. Sending OpenRouter-only knobs to other providers — 공식 하위 절. 구현·설정 세부 원문 참조.

Good search targets while implementing

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

이 절의 절차·표·코드는 공식 원문을 기준으로 적용한다.

체크리스트

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

다음 단계

기준일: 2026-07-26 — 공식 문서 동기화 코퍼스

Provider 추가

개요

핵심 개념

상세

멘탈 모델

구현 경로 먼저 선택

파일 체크리스트

빠른 경로: 단순 API 키 provider

전체 경로: OAuth·복잡 provider

Step 1: Pick one canonical provider id

Step 2: Add auth metadata in hermes_cli/auth.py

Step 3: Add model catalog and aliases in hermes_cli/models.py

Step 4: Resolve runtime data in hermes_cli/runtime_provider.py

Step 5: Wire the CLI in hermes_cli/main.py

Step 6: Keep auxiliary calls working

Step 7: If the provider is native, add an adapter and run_agent.py support

Step 8: Tests

Step 9: Live verification

Step 10: Update user-facing docs

OpenAI-compatible provider checklist

Native provider checklist

Common pitfalls

Good search targets while implementing

Related docs

체크리스트

다음 단계

관련 가이드

Provider 추가

개요

핵심 개념

상세

멘탈 모델

구현 경로 먼저 선택

파일 체크리스트

빠른 경로: 단순 API 키 provider

전체 경로: OAuth·복잡 provider

Step 1: Pick one canonical provider id

Step 2: Add auth metadata in hermes_cli/auth.py

Step 3: Add model catalog and aliases in hermes_cli/models.py

Step 4: Resolve runtime data in hermes_cli/runtime_provider.py

Step 5: Wire the CLI in hermes_cli/main.py

Step 6: Keep auxiliary calls working

Step 7: If the provider is native, add an adapter and run_agent.py support

Step 8: Tests

Step 9: Live verification

Step 10: Update user-facing docs

OpenAI-compatible provider checklist

Native provider checklist

Common pitfalls

Good search targets while implementing

Related docs

체크리스트

다음 단계

관련 가이드

Step 2: Add auth metadata in `hermes_cli/auth.py`

Step 3: Add model catalog and aliases in `hermes_cli/models.py`

Step 4: Resolve runtime data in `hermes_cli/runtime_provider.py`

Step 5: Wire the CLI in `hermes_cli/main.py`

Step 7: If the provider is native, add an adapter and `run_agent.py` support

Step 2: Add auth metadata in `hermes_cli/auth.py`

Step 3: Add model catalog and aliases in `hermes_cli/models.py`

Step 4: Resolve runtime data in `hermes_cli/runtime_provider.py`

Step 5: Wire the CLI in `hermes_cli/main.py`

Step 7: If the provider is native, add an adapter and `run_agent.py` support