Provider runtime resolution is the system that determines which LLM provider to use for a request and obtains the necessary credentials, base URLs, and model configurations at execution time. This enables dynamic provider switching, multi-credential failover, and automatic protocol adaptation (OpenAI, Anthropic, or Codex) without hardcoded dependencies.
The resolution system operates in multiple stages:
openrouter, anthropic, openai-codex, xai, etc.) is requested based on model prefixes or explicit configuration hermes_cli/runtime_provider.py31-39~/.hermes/auth.json file hermes_cli/runtime_provider.py16-32chat_completions, anthropic_messages, or codex_responses) hermes_cli/runtime_provider.py101-139ProviderTransport instance configured with the resolved parameters to handle message formatting and response normalization agent/transports/chat_completions.py131-140Two separate resolution chains exist:
AIAgent constructor which maps models to transports run_agent.py45-53Sources: hermes_cli/runtime_provider.py1-45 agent/auxiliary_client.py1-41 run_agent.py45-57 agent/transports/chat_completions.py131-140
Hermes supports a wide array of provider prefixes in model strings. If a model is specified as provider:model_id, the system identifies the target backend while preserving provider-specific syntax like Ollama's :latest tags agent/model_metadata.py89-106
| Prefix Category | Examples |
|---|---|
| Global Gateways | openrouter, nous, ollama-cloud agent/model_metadata.py50-53 |
| Native Providers | anthropic, deepseek, gemini, xai, nvidia agent/model_metadata.py52-71 |
| Specialized/OAuth | minimax-oauth, qwen-oauth, copilot-acp agent/model_metadata.py51-54 |
| Aggregators | opencode-zen, kilo, novita, deepinfra agent/model_metadata.py52-53 |
The _strip_provider_prefix function ensures that provider identifiers are handled correctly without breaking model-specific tags like qwen3.5:27b agent/model_metadata.py89-106
Sources: agent/model_metadata.py50-73 agent/model_metadata.py89-106
Hermes uses a plugin-like architecture for communication protocols, detected automatically from the provider ID or base URL.
The default transport used for most providers. The ChatCompletionsTransport handles complex logic for Gemini thinking configs agent/transports/chat_completions.py35-88 and strips internal scaffolding markers that strict providers might reject agent/transports/chat_completions.py141-160
Used for native Claude models and Anthropic-compatible endpoints like Kimi Code hermes_cli/runtime_provider.py137-138
anthropic_messages for api.anthropic.com or paths ending in /anthropic hermes_cli/runtime_provider.py132-136/coding endpoint is specifically mapped to the Anthropic protocol hermes_cli/runtime_provider.py137-138A specialized transport for OpenAI Codex and xAI's /v1/responses agent/transports/codex.py107-111
codex_responses for api.openai.com or api.x.ai hostnames hermes_cli/runtime_provider.py124-127Sources: hermes_cli/runtime_provider.py101-139 agent/transports/chat_completions.py131-160 agent/transports/codex.py107-123 agent/codex_responses_adapter.py26-50
This diagram illustrates how a user-provided model string is resolved into a functional client and transport.
Title: Provider Resolution Pipeline
Sources: hermes_cli/runtime_provider.py16-38 agent/model_metadata.py89-106 hermes_cli/runtime_provider.py101-139 run_agent.py45-53
The auxiliary client system provides a robust fallback chain for non-primary tasks like context compression or vision analysis.
Title: Auxiliary Fallback Chain
call_llm function automatically retries with the next available provider in the chain agent/auxiliary_client.py36-41auxiliary.vision.provider) in config.yaml bypass the automatic resolution chain agent/auxiliary_client.py32-34Sources: agent/auxiliary_client.py1-41 agent/auxiliary_client.py116-131
The system maintains a multi-tier cache for model metadata and context lengths to prevent redundant API calls and handle unknown models gracefully.
~/.hermes/cache/openrouter_model_metadata.json agent/model_metadata.py127-130/api/v1/models and caches the result for 300 seconds agent/model_metadata.py115-123When a model's context length is unknown, Hermes uses descending tiers to find a working window agent/model_metadata.py181-188
| Tier | Tokens |
|---|---|
| Tier 0 | 256,000 |
| Tier 1 | 128,000 |
| Tier 2 | 64,000 |
| Tier 3 | 32,000 |
| Tier 4 | 16,000 |
| Tier 5 | 8,000 |
Sources: agent/model_metadata.py108-125 agent/model_metadata.py127-144 agent/model_metadata.py181-188
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.