From 3204bfa5e27cdd9552a641476d9c33ccf3f464f2 Mon Sep 17 00:00:00 2001 From: Ayush Nangia Date: Thu, 6 Aug 2026 22:44:46 +0530 Subject: [PATCH] docs+defaults: declare delegation.fallback_providers in config surfaces Adopted from PR #80421 with the author's explicit go-ahead on #80450 ('Please proceed!'): config_defaults entry, cli-config.yaml.example block, and user-guide docs for the delegation-scoped fallback chain. Co-authored-by: Andrex Ibiza, MBA <84248988+andrexibiza@users.noreply.github.com> --- cli-config.yaml.example | 3 +++ hermes_cli/config_defaults.py | 5 +++++ website/docs/user-guide/configuration.md | 3 ++- website/docs/user-guide/features/fallback-providers.md | 2 +- 4 files changed, 11 insertions(+), 2 deletions(-) diff --git a/cli-config.yaml.example b/cli-config.yaml.example index 841cb60221..6785e52c97 100644 --- a/cli-config.yaml.example +++ b/cli-config.yaml.example @@ -1662,6 +1662,9 @@ delegation: # # delegation.model to an inexpensive one — children carry the # # vast majority of tokens, so this is where spend is cut while # # planning quality stays with the frontier parent. + # fallback_providers: # Fallback chain for delegated children (same entry format as the + # - provider: "openrouter" # top-level fallback_providers list). Unset = inherit the parent + # model: "deepseek/deepseek-chat" # agent's chain; [] = disable child fallback entirely (#65038). # ============================================================================= # Honcho Integration (Cross-Session User Modeling) diff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.py index 771bff9320..3451a15287 100644 --- a/hermes_cli/config_defaults.py +++ b/hermes_cli/config_defaults.py @@ -1211,6 +1211,11 @@ DEFAULT_CONFIG = { "delegation": { "model": "", # e.g. "google/gemini-3-flash-preview" (empty = inherit parent) "provider": "", # e.g. "openrouter" (empty = inherit parent provider + credentials) + # Fallback chain for delegated children (same entry format as the top-level list). + # For an unpinned child, null = inherit the parent chain; [] = disable fallback. + # A child pinned by provider, endpoint, or model gets no fallback unless this + # setting declares one explicitly. + "fallback_providers": None, "base_url": "", # direct OpenAI-compatible endpoint for subagents "api_key": "", # key for delegation.base_url (falls back to OPENAI_API_KEY) # Wire protocol for delegation.base_url: "chat_completions" | "codex_responses" | diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md index f7e851950e..a611274553 100644 --- a/website/docs/user-guide/configuration.md +++ b/website/docs/user-guide/configuration.md @@ -2704,6 +2704,8 @@ delegation: **Subagent provider:model override:** By default, subagents inherit the parent agent's provider and model. Set `delegation.provider` and `delegation.model` to route subagents to a different provider:model pair — e.g., use a cheap/fast model for narrowly-scoped subtasks while your primary agent runs an expensive reasoning model. +**Subagent fallback chain:** Set `delegation.fallback_providers` to give workers their own chain (same entry shape as the top-level list). An explicitly pinned child (by provider, endpoint, or model) uses that chain only when it is declared; otherwise it fails loudly instead of borrowing the parent agent's route. For an unpinned child, an absent or `null` setting preserves parent-chain inheritance. Use `fallback_providers: []` under `delegation:` to disable child fallback entirely. + **Direct endpoint override:** If you want the obvious custom-endpoint path, set `delegation.base_url`, `delegation.api_key`, and `delegation.model`. That sends subagents directly to that OpenAI-compatible endpoint and takes precedence over `delegation.provider`. If `delegation.api_key` is omitted, Hermes falls back to `OPENAI_API_KEY` only. When `delegation.provider` is set alongside `delegation.base_url`, the explicit endpoint and key still win, but that provider's request settings (`extra_body` overrides and max output tokens from your `custom_providers` entry) are carried into the subagent. **Per-child request settings (`request_overrides`):** `delegation.request_overrides` is a dict of request settings sent on every subagent API call. Top-level keys are API kwargs (e.g. `service_tier`); an `extra_body` sub-dict is merged into the request's `extra_body`. It is honored on **all three** resolution branches — direct `base_url`, named `provider`, and pure inherit — so the key always takes effect. Precedence: explicit `request_overrides` values merge **over** any runtime- or parent-derived overrides — top-level explicit keys win, and `extra_body` is deep-merged one level so runtime `extra_body` keys (e.g. a provider's `thinking: {type: disabled}` personality) survive unless your key redefines them. The canonical use case is OpenRouter routing hints for delegation children: @@ -2718,7 +2720,6 @@ delegation: provider: sort: throughput # route children to the fastest OpenRouter provider ``` - **Wire protocol (`api_mode`):** Hermes auto-detects the wire protocol from `delegation.base_url` (e.g. paths ending in `/anthropic` → `anthropic_messages`; Codex / native Anthropic / Kimi-coding hostnames keep their existing detection). For endpoints the heuristic can't classify — for example Azure AI Foundry, MiniMax, Zhipu GLM, or LiteLLM proxies fronting an Anthropic-shaped backend — set `delegation.api_mode` explicitly to one of `chat_completions`, `codex_responses`, or `anthropic_messages`. Leave it empty (the default) to keep auto-detection. The delegation provider uses the same credential resolution as CLI/gateway startup. All configured providers are supported: `openrouter`, `nous`, `copilot`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`. When a provider is set, the system automatically resolves the correct base URL, API key, and API mode — no manual credential wiring needed. diff --git a/website/docs/user-guide/features/fallback-providers.md b/website/docs/user-guide/features/fallback-providers.md index dc0b01f5e5..3a6b6c8797 100644 --- a/website/docs/user-guide/features/fallback-providers.md +++ b/website/docs/user-guide/features/fallback-providers.md @@ -185,7 +185,7 @@ fallback_providers: |---------|-------------------| | CLI sessions | ✔ | | Messaging gateway (Telegram, Discord, etc.) | ✔ | -| Subagent delegation | ✔ (subagents inherit the parent fallback chain) | +| Subagent delegation | ✔ (`delegation.fallback_providers` when set; otherwise inherit parent chain; `[]` disables) | | Cron jobs | ✔ (cron agents inherit configured fallback providers) | | Auxiliary tasks on `provider: auto` | ✔ (try per-task fallback, then the main fallback chain before built-in aux discovery) |