PR #24918: feat(agent): support user-provided extra CA bundles for OpenAI/httpx clients

• Repository: NousResearch/hermes-agent
• Author: MMMarcinho
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/24918

Description (problem / solution / changelog)

Summary

This adds generic extra CA bundle support for Hermes' Python/httpx-based OpenAI client path.

When users configure extra CA cert files via HERMES_EXTRA_CA_CERTS or NODE_EXTRA_CA_CERTS, Hermes now builds a merged CA bundle and uses it for the keepalive-enabled httpx client used by the main agent.

This helps in environments where an HTTPS proxy presents certificates signed by a local/private root CA. The change keeps TLS verification enabled and does not hardcode any organization, vendor, or company-specific CA paths.

Closes #24917.

Details

New helper: configure_extra_ca_bundle()

Added in utils.py.

The helper:

• reads extra CA paths from:
  • HERMES_EXTRA_CA_CERTS
  • NODE_EXTRA_CA_CERTS
• supports path-list values using os.pathsep
• filters missing files
• deduplicates cert paths
• builds a merged CA bundle from:
  • existing SSL_CERT_FILE or REQUESTS_CA_BUNDLE, when configured
  • otherwise certifi.where()
  • otherwise Python's default SSL cafile
• writes the merged bundle to:
  • HERMES_CA_BUNDLE, if set
  • otherwise $HERMES_HOME/hermes-ca-bundle.pem
• sets:
  • SSL_CERT_FILE
  • REQUESTS_CA_BUNDLE
• stores the original base bundle in _HERMES_CA_BASE_BUNDLE so repeated calls are idempotent
• supports opt-out via HERMES_DISABLE_EXTRA_CA_AUTO

Proxy normalization path

normalize_proxy_env_vars() now calls configure_extra_ca_bundle() after normalizing proxy env vars.

This keeps proxy and TLS trust configuration on the same runtime initialization path.

Main OpenAI/httpx client

AIAgent._build_keepalive_http_client() now calls configure_extra_ca_bundle().

If a merged bundle is available, the httpx client receives:

ssl.create_default_context(cafile=bundle_path)

This preserves the existing keepalive transport and explicit proxy handling while also allowing Python/httpx to trust user-provided extra CA roots.

The implementation uses an SSLContext instead of verify=<str> to avoid httpx's deprecation warning for string verify paths.

Why this is needed

Hermes can already route requests through proxies, but proxy routing alone is not sufficient when the proxy presents certificates signed by a CA that Python/httpx does not trust.

Some users already have extra CA configuration for Node-based tools via NODE_EXTRA_CA_CERTS, but Hermes' Python/httpx clients do not automatically consume that setting.

Gateway mode also has a specific ordering issue: SSL_CERT_FILE may be set before .env is loaded. The new helper handles this by merging extra CA files even when SSL_CERT_FILE is already present.

Tests

Added regression coverage in tests/run_agent/test_create_openai_client_proxy_env.py:

• existing proxy tests now clear CA-related env vars to avoid cross-test contamination
• extra CA bundle is merged when SSL_CERT_FILE is preconfigured
• repeated calls are idempotent and do not duplicate extra CA contents

How to test

env HERMES_HOME=/private/tmp/hermes-pytest \
  venv/bin/python -m pytest \
  tests/run_agent/test_create_openai_client_proxy_env.py \
  tests/agent/test_proxy_and_url_validation.py

All 27 tests pass.

Platforms tested

• macOS 15.x (darwin, arm64)

Validation

• git diff --check: passed
• Targeted tests: 27 passed
• Full suite (scripts/run_tests.sh): 22,000+ passed, failures are pre-existing (optional deps: discord, faster_whisper, bedrock)

Changed files

• run_agent.py (modified, +10/-5)
• tests/run_agent/test_create_openai_client_proxy_env.py (modified, +76/-0)
• utils.py (modified, +125/-0)