Auxiliary Client

Relevant source files

• .env.example
• AGENTS.md
• README.md
• agent/anthropic_adapter.py
• agent/auxiliary_client.py
• agent/bedrock_adapter.py
• agent/message_sanitization.py
• agent/transports/__init__.py
• agent/transports/anthropic.py
• agent/transports/types.py
• agent/usage_pricing.py
• cli-config.yaml.example
• cli.py
• gateway/run.py
• hermes_cli/auth.py
• hermes_cli/commands.py
• hermes_cli/config.py
• hermes_cli/main.py
• hermes_cli/model_setup_flows.py
• hermes_cli/models.py
• hermes_cli/runtime_provider.py
• hermes_cli/setup.py
• run_agent.py
• tests/agent/test_anthropic_adapter.py
• tests/agent/test_anthropic_mcp_prefix_strip.py
• tests/agent/test_anthropic_oauth_ua_prefix.py
• tests/agent/test_anthropic_output_field_leak.py
• tests/agent/test_anthropic_whitespace_text_blocks.py
• tests/agent/test_auxiliary_client.py
• tests/agent/test_bedrock_adapter.py
• tests/agent/test_bedrock_integration.py
• tests/agent/test_bedrock_interrupt_post_worker.py
• tests/agent/test_close_interrupted_tool_sequence.py
• tests/agent/test_usage_pricing.py
• tests/agent/transports/test_transport.py
• tests/agent/transports/test_types.py
• tests/cli/test_cli_provider_resolution.py
• tests/gateway/test_dingtalk.py
• tests/gateway/test_feishu_bot_admission.py
• tests/hermes_cli/test_bedrock_model_picker.py
• tests/hermes_cli/test_bedrock_region_scoped_picker.py
• tests/hermes_cli/test_commands.py
• tests/hermes_cli/test_custom_provider_model_switch.py
• tests/hermes_cli/test_gpt56_registration.py
• tests/hermes_cli/test_model_provider_persistence.py
• tests/hermes_cli/test_model_validation.py
• tests/hermes_cli/test_reasoning_effort_menu.py
• tests/hermes_cli/test_runtime_provider_resolution.py
• tests/hermes_cli/test_terminal_menu_fallbacks.py
• tests/run_agent/test_anthropic_truncation_continuation.py
• tests/run_agent/test_repair_tool_call_arguments.py
• tests/run_agent/test_stream_single_writer_65991.py
• tests/run_agent/test_streaming.py
• tests/test_minisweagent_path.py
• tests/tools/test_terminal_requirements.py
• tests/tools/test_terminal_tool_requirements.py
• tests/tools/test_tts_kittentts.py

Purpose and Scope

The auxiliary client is a centralized subsystem designed to handle LLM invocations for side tasks that are distinct from the primary conversation model. These side tasks include:

• Text-focused auxiliary tasks: Web content extraction, session search, session context compression, and title generation. agent/auxiliary_client.py1-5 agent/auxiliary_client.py137-140
• Vision or multimodal auxiliary tasks: Image analysis for vision tools and browser screenshot understanding. agent/auxiliary_client.py17-23

The auxiliary client system provides a unified provider resolution chain and client instantiation logic, enabling shared and consistent fallback behavior across different consumers. This shields main agent conversation workloads and their context windows from heavy summarization or specialized processing demands, offloading these to cheaper or task-specialized backends. agent/auxiliary_client.py3-6

It supports a wide variety of providers including OpenRouter, Nous Portal OAuth, local/self-hosted custom endpoints, OpenAI Codex OAuth, native Anthropic, and direct API-key providers such as Google Gemini, Kimi/Moonshot, and MiniMax. The system also handles transparent payment/credit exhaustion fallbacks by retrying with the next available provider. agent/auxiliary_client.py36-41

Sources: agent/auxiliary_client.py1-41 agent/auxiliary_client.py131-160

---

Architecture Overview

The auxiliary client provides a centralized provider routing and fallback system. Instead of each tool implementing its own provider and credential resolution, this system allows all auxiliary consumers to reuse a common resolution chain which selects the best available backend per task type and configured overrides.

This centralized routing enables:

• Per-task override: Configuration via config.yaml under the auxiliary: section (e.g., auxiliary.vision.provider, auxiliary.compression.model). agent/auxiliary_client.py32-34
• Auto-detection chains: Logic to find usable credentials and endpoints at runtime across environment variables and stored auth. agent/auxiliary_client.py7-23
• Automatic Fallback: Consistent retry behavior on payment/credit errors (HTTP 402) by moving to the next provider in the chain. agent/auxiliary_client.py36-41
• Provider Adapters: Specialized handling for non-OpenAI protocols like Anthropic. agent/anthropic_adapter.py1-11

Per-Task Provider Resolution

Auxiliary tasks specify their provider and model via configuration. The client employs the following steps for resolution:

1. Check for a per-task explicit provider override in the configuration via _resolve_task_provider_model. agent/auxiliary_client.py113-132
2. If set to "auto", apply the automatic provider priority chain defined in _resolve_auto(). agent/auxiliary_client.py7-23 agent/auxiliary_client.py22-38
3. For the resolved provider, check for a per-task model override. agent/auxiliary_client.py32-34
4. Instantiate and return a complete client ready for usage via resolve_provider_client. agent/auxiliary_client.py116-130

Diagram: Task to Provider Resolution

Sources: agent/auxiliary_client.py7-41 agent/auxiliary_client.py113-132 agent/auxiliary_client.py116-130

---

Provider Resolution Chain

Automatic Provider Resolution

The auxiliary client implements resolution chains that attempt the following provider priorities in order for text tasks:

Priority	Provider	Credential / Config Source	Notes
1	Main Provider	_read_main_provider()	Uses the user's primary agent model/provider. agent/auxiliary_client.py8-9
2	OpenRouter	OPENROUTER_API_KEY	Aggregated cloud API provider. agent/auxiliary_client.py10
3	Nous Portal	~/.hermes/auth.json	OAuth authentication via Nous Research. agent/auxiliary_client.py11
4	Custom Endpoint	OPENAI_BASE_URL + OPENAI_API_KEY	For local/self-hosted endpoints. agent/auxiliary_client.py12
5	Native Anthropic	ANTHROPIC_API_KEY	Direct SDK integration. agent/auxiliary_client.py13
6	Direct API Key	z.ai, Kimi, MiniMax keys	Direct integration for specific families. agent/auxiliary_client.py14

Vision/Multimodal task provider resolution prioritize supported vision backends like OpenRouter, Nous Portal, and Native Anthropic. agent/auxiliary_client.py17-23

Sources: agent/auxiliary_client.py7-15 agent/auxiliary_client.py113-132

---

Client Types and Adapters

Anthropic Native Adapter

Hermes Agent includes a native adapter for Anthropic's Messages API in agent/anthropic_adapter.py. This adapter translates Hermes's internal OpenAI-style message format to Anthropic's message schema. agent/anthropic_adapter.py1-11

Highlights:

• Reasoning Effort → Thinking Budget: Maps Hermes Agent's reasoning_effort levels to Anthropic's output_config.effort via THINKING_BUDGET and ADAPTIVE_EFFORT_MAP. agent/anthropic_adapter.py58-74
• Model-Specific Output Token Limits: Derived via _get_anthropic_max_output(). For example, claude-opus-4-8 is capped at 128,000 tokens. agent/anthropic_adapter.py126-150
• Adaptive Thinking Logic: Detects models that support or require adaptive thinking (e.g., 4.6, 4.7, and 4.8 series) and adjusts parameters accordingly. agent/anthropic_adapter.py85-89
• Auth Support: Handles regular API keys (sk-ant-api*), OAuth setup-tokens (sk-ant-oat*), and Claude Code credentials. agent/anthropic_adapter.py7-11

Diagram: Anthropic Adapter Data Flow

Sources: agent/anthropic_adapter.py58-74 agent/anthropic_adapter.py126-150 agent/anthropic_adapter.py179-182

---

OpenAI Codex Responses Adapter

For users authenticated via the OpenAI Codex OAuth flow, Hermes implements a shim to convert OpenAI-style chat completion requests into the Codex Responses API JSON format. This is handled by the _CodexCompletionsAdapter class in agent/auxiliary_client.py. agent/auxiliary_client.py25-30

Operation highlights:

• Translates chat/completions requests to the Codex transport. agent/auxiliary_client.py25-30
• Handles model allow-lists which are often shifting for Codex endpoints. agent/auxiliary_client.py25-30
• Integrated into the _resolve_auto() chain. agent/auxiliary_client.py10-15

Sources: agent/auxiliary_client.py25-30 agent/auxiliary_client.py10-15

---

Smart Routing and Fallbacks

Credential Pool and Runtime Resolution

Credential management and runtime provider instantiation leverage the CredentialPool and ProviderProfile systems:

• Provider Normalization: _normalize_aux_provider() maps aliases like google to gemini or claude to anthropic to ensure consistent resolution. agent/auxiliary_client.py28-38
• Credential Rotation: The client consults the CredentialPool to find valid, non-expired credentials for the target task. agent/credential_pool.py1-15
• Provider Resolution: resolve_provider() in hermes_cli/auth.py picks the active provider via a priority chain. hermes_cli/auth.py31-39

Payment and Error Handling Fallback

When an auxiliary LLM call returns an HTTP 402 Payment Required or a credit exhaustion error, the system automatically retries with the next candidate provider in the auto-detection order via _try_payment_fallback(). agent/auxiliary_client.py36-41

Sources: agent/auxiliary_client.py36-41 hermes_cli/auth.py31-39

---

Summary Table: Provider Resolution vs. Code Entities

Natural Language Task	Code Function / Class	Backend Implementation (Code File)
Auxiliary Routing	resolve_provider_client()	agent/auxiliary_client.py
Auth Chain	_resolve_auto()	agent/auxiliary_client.py
Anthropic Adaptation	build_anthropic_client()	agent/anthropic_adapter.py
Codex Mapping	_CodexCompletionsAdapter	agent/auxiliary_client.py
Credential Management	load_pool()	agent/credential_pool.py
Runtime Detection	_detect_api_mode_for_url()	hermes_cli/runtime_provider.py

Sources: agent/auxiliary_client.py1-41 agent/anthropic_adapter.py1-11 hermes_cli/runtime_provider.py101-139