Files

teknium1 d87a1615ce docs: add ACP and internal systems implementation guides

- add ACP user and developer docs covering setup, lifecycle, callbacks,
  permissions, tool rendering, and runtime behavior
- add developer guides for agent loop, provider runtime resolution,
  prompt assembly, context caching/compression, gateway internals,
  session storage, tools runtime, trajectories, and cron internals
- refresh architecture, quickstart, installation, CLI reference, and
  environments docs to link the new implementation pages and ACP support

2026-03-14 00:29:48 -07:00

2.6 KiB

Raw Blame History

sidebar_position, title, description

sidebar_position	title	description
4	Provider Runtime Resolution	How Hermes resolves providers, credentials, API modes, and auxiliary models at runtime

Provider Runtime Resolution

Hermes has a shared provider runtime resolver used across:

CLI
gateway
cron jobs
ACP
auxiliary model calls

Primary implementation:

hermes_cli/runtime_provider.py
hermes_cli/auth.py
agent/auxiliary_client.py

Resolution precedence

At a high level, provider resolution uses:

explicit CLI/runtime request
environment variables
config.yaml model/provider config
provider-specific defaults or auto resolution

Providers

Current provider families include:

OpenRouter
Nous Portal
OpenAI Codex
Anthropic (native)
Z.AI
Kimi / Moonshot
MiniMax
MiniMax China
custom OpenAI-compatible endpoints

Output of runtime resolution

The runtime resolver returns data such as:

provider
api_mode
base_url
api_key
source
provider-specific metadata like expiry/refresh info

Why this matters

This resolver is the main reason Hermes can share auth/runtime logic between:

hermes chat
gateway message handling
cron jobs running in fresh sessions
ACP editor sessions
auxiliary model tasks

OpenRouter vs custom OpenAI-compatible base URLs

Hermes contains logic to avoid leaking the wrong API key to a custom endpoint when both OPENROUTER_API_KEY and OPENAI_API_KEY exist.

That distinction is especially important for:

local model servers
non-OpenRouter OpenAI-compatible APIs
switching providers without re-running setup

Native Anthropic path

Anthropic is not just "via OpenRouter" anymore.

When provider resolution selects anthropic, Hermes uses:

api_mode = anthropic_messages
the native Anthropic Messages API
agent/anthropic_adapter.py for translation

OpenAI Codex path

Codex uses a separate Responses API path:

api_mode = codex_responses
dedicated credential resolution and auth store support

Auxiliary model routing

Auxiliary tasks such as:

vision
web extraction summarization
context compression summaries
session search summarization
skills hub operations
MCP helper operations
memory flushes

can use their own provider/model routing rather than the main conversational model.

Fallback models

Hermes also supports a configured fallback model/provider, allowing runtime failover in supported error paths.

2.6 KiB Raw Blame History