hermes - 💡(How to fix) Fix [Bug] Volcengine Ark API fails with HTTP 400 due to User-Agent fingerprinting - need custom headers support for providers [1 comments, 2 participants]

 When using Volcengine (火山引擎) Ark API as a custom provider, all requests fail with:

 HTTP 400: A parameter specified in the request is not valid

 This error happens silently without any clear indication of what parameter is invalid. After extensive debugging, the root cause was discovered:

 Volcengine Ark API actively blocks requests with the OpenAI SDK default User-Agent (OpenAI/Python 2.x.x).

 The API returns a generic 400 error with no useful message, making this extremely hard to diagnose.
 Workaround

 Changing the User-Agent to literally anything else (e.g., curl/8.0) makes the API work perfectly.
 Proposed Fix

 Add support for custom headers in the provider configuration that get passed to the OpenAI client as default_headers.
 Files Modified (working implementation)

 The fix requires changes in 4 files:

 1. hermes_cli/config.py (2 changes)
    - Add "headers" to _KNOWN_KEYS set (line ~2266)
    - Add normalization code to extract headers from provider config (line ~2357-2359)
    python
    headers = entry.get("headers")
    if isinstance(headers, dict) and headers:
        normalized["headers"] = headers


 2. hermes_cli/runtime_provider.py (line ~552-555)
    - Propagate custom headers to runtime result dict
    python
    custom_headers = custom_provider.get("headers")
    if isinstance(custom_headers, dict) and custom_headers:
        result["headers"] = custom_headers


 3. run_agent.py (2 changes)
    - Add headers: Dict[str, str] = None parameter to AIAgent.init signature (line ~850)
    - Store self.headers = headers (line ~979)
    - Apply custom headers to OpenAI client (line ~1376-1380)
    python
    if isinstance(self.headers, dict) and self.headers:
        existing = client_kwargs.get("default_headers", {})
        existing.update(self.headers)
        client_kwargs["default_headers"] = existing


 4. agent/auxiliary_client.py (line ~1945-1948)
    - Apply custom headers in resolve_provider_client for named custom providers
    python
    custom_headers = custom_entry.get("headers")
    if isinstance(custom_headers, dict) and custom_headers:
        _extra2["default_headers"] = custom_headers

 User Config

 After the fix, users can configure Volcengine Ark like this in ~/.hermes/config.yaml:

 yaml
 providers:
   ark:
     name: ark
     api: openai
     url: https://ark.cn-beijing.volces.com/api/coding/v3
     api_key: your-api-key-here
     model: ark-code-latest
     headers:
       User-Agent: curl/8.0

 Why This Is Important

 1. Volcengine Ark is a popular and cost-effective LLM provider in China
 2. The error message is completely misleading, making this very hard to debug
 3. Custom headers support is generally useful for many other self-hosted/enterprise API endpoints that require special headers for auth, rate limiting, or internal routing