Hermes Council: Multi-Agent Deliberation for Hermes Agent

How It Works

Architecture

The architecture follows a clear pipeline from Hermes Agent to a structured verdict:

Hermes Agent
    |
    | MCP stdio tool call
    v
hermes-council server
    |
    +--> optional evidence retrieval
    |       - fetch supplied URLs
    |       - optional DuckDuckGo HTML search
    |       - block localhost/private IP targets
    |
    +--> parallel deliberators
    |       - Advocate: steel-man the proposal
    |       - Skeptic: find falsifiers and failure modes
    |       - Oracle: base rates and empirical grounding
    |       - Contrarian: challenge the framing
    |
    +--> Arbiter
            - synthesize disagreement
            - emit structured JSON verdict
            - produce risks, checks, actions, DPO pairs

The server uses an OpenAI-compatible async client. It tries JSON mode first and falls back to text parsing when a provider rejects response_format.

Evidence Model

When evidence_search=true, retrieval runs before persona calls. The evidence layer produces three fields:

Security boundaries:

• Only http and https URLs are fetched.
• Localhost, private IPs, link-local IPs, multicast, reserved, and unspecified IPs are blocked before fetch.
• Set COUNCIL_EVIDENCE_SEARCH=0 to disable DuckDuckGo search while still allowing supplied public URLs to be fetched.

Tools

Hermes Agent exposes MCP tools with a server prefix. With the config above, the runtime names are mcp_council_council_query, mcp_council_council_gate, and so on.

Gate Output Example

{
  "success": true,
  "verdict": "allow_with_conditions",
  "allowed": true,
  "can_proceed_now": false,
  "required_checks": ["verify rollback", "run dry-run"],
  "blocking_risks": ["rollback untested"],
  "safe_alternative": "stage the action first",
  "action_summary": {
    "recommendation": "Proceed after verifying rollback and dry-run output.",
    "top_risks": ["rollback untested"],
    "missing_evidence": ["dry-run output"],
    "next_actions": ["run dry-run", "verify rollback"]
  }
}

Project Layout

hermes-council/
  src/hermes_council/
    server.py          # FastMCP stdio server and public tool handlers
    deliberation.py    # persona orchestration, modes, JSON negotiation, DPO pairs
    evidence.py        # URL/search evidence retrieval and SSRF guards
    audit.py           # optional local JSON verdict logs
    client.py          # provider config and AsyncOpenAI singleton
    personas.py        # default and custom persona definitions
    schemas.py         # Pydantic models for structured model output
    parsing.py         # fallback text parsers for non-JSON providers
    cli.py             # skill installer
    rl/evaluator.py    # direct evaluator API for reward and DPO workflows
  skills/council/      # packaged Hermes skill definitions
  examples/            # Atropos/Ouroboros evaluator example
  tests/               # unit, integration, packaging, and MCP runtime tests
  docs/plans/          # original design and implementation notes

Requirements and Limitations

• Python version: 3.11 or higher, as indicated by the badge in the repository.
• Provider key required: A real provider key is required for actual model-backed verdicts. The server will not produce meaningful output without one.
• DuckDuckGo search reliability: DuckDuckGo HTML search can change; supplied URLs are more reliable than search results.
• Evidence truth: verified_sources proves retrieval, not truth. The Arbiter still weighs the evidence.
• Transport: The server is stdio MCP only. There is no hosted HTTP service in this repo.
• Latency and cost: The council adds latency and token cost. Use fast mode for routine preflight.
• Model compliance: Model compliance with JSON fields depends on provider/model behavior, though fallback parsing is implemented.
• No bundled config in Hermes Agent: The maintainers of Hermes Agent do not bundle third-party MCP server references in cli-config.yaml.example or optional-skills/ to avoid endorsing one community server over others. Install standalone via the Quickstart above; the server is designed to run that way.

Troubleshooting

Server fails to start

If python -m hermes_council.server fails, check that the package installed cleanly. The smoke test is designed to verify that the module entrypoint imports cleanly. If it does not, reinstall with pip install --force-reinstall "hermes-council @ git+https://github.com/Ridwannurudeen/hermes-council.git".

No key configured

The test suite covers Hermes-compatible no-key failure behavior. If you see errors about missing API keys, set one of the supported environment variables according to the priority order: COUNCIL_API_KEY, OPENROUTER_API_KEY, NOUS_API_KEY, or OPENAI_API_KEY.

Evidence retrieval fails for certain URLs

If evidence retrieval fails for a URL, check that it uses http or https. Localhost, private IPs, link-local IPs, multicast, reserved, and unspecified IPs are blocked before fetch. Non-fatal retrieval errors are reported in the evidence_errors field of the verdict.

DuckDuckGo search stops working

DuckDuckGo HTML search can change without notice. If search results stop appearing, set COUNCIL_EVIDENCE_SEARCH=0 to disable DuckDuckGo search while still allowing supplied public URLs to be fetched. Supplied URLs are more reliable than search results.

Model refuses JSON mode

The server uses an OpenAI-compatible async client. It tries JSON mode first and falls back to text parsing when a provider rejects response_format. If you see malformed output, it may be a provider compatibility issue. The fallback parser handles this, but model compliance with JSON fields depends on provider/model behavior.

Tools not appearing in Hermes Agent

If the MCP tools do not appear after configuration, restart Hermes Agent or run /reload-mcp. Verify the config in ~/.hermes/config.yaml matches the example exactly. The runtime names will have a server prefix, e.g., mcp_council_council_query.