Hermes Council

hermes-council

Adversarial preflight and decision review for Hermes Agent.

Hermes Council is an MCP server that lets Hermes Agent stress-test plans, diffs, claims, decisions, and risky actions before it acts. It returns structured verdicts, verified evidence snippets, required checks, and DPO preference pairs for evaluator and RL workflows.

Why | What it does | Quickstart | Tools | Architecture | Development

为什么它存在

自主代理是有用的，因为它们会行动。这也是他们失败的地方。 故障模式通常不是语法错误；这是一个过于自信的计划 微弱的声明、不安全的命令、看似合理但打破界限的差异， 或者本应通过一次对抗性审查来阻止的部署。

赫尔墨斯委员会为赫尔墨斯特工提供了一个专门的判断层。在代理人之前 发送计划、更改代码、接受索赔或采取冒险行动，它可以调用 一个迫使多种知识传统争论、异议和 产生一个结构化的最终判决。

结果并不是另一条长长的思维链。它是一个MCP工具集 明确的判决字段： allow, allow_with_conditions, deny, top_risks, required_checks, missing_evidence, verified_sources，以及 next_actions.

它的作用

Preflight risky actions Review deploys, migrations, file operations, public messages, and other high-stakes actions before execution. Returns a verdict, blocking risks, required checks, and safer alternatives. Review plans and diffs Stress-test implementation plans and code diffs for bugs, missing tests, integration failures, security regressions, and weak assumptions.

Fact-check claims with evidence Fetch supplied URLs, optionally search the web, pass source snippets to the council, and separate verified_sources from model-cited sources. Compare decisions Evaluate multiple options against explicit criteria and return one recommended path with risks, evidence gaps, and next actions.

Run adversarial deliberation Use Advocate, Skeptic, Oracle, Contrarian, and Arbiter personas to expose disagreement and synthesize a calibrated verdict. Produce RL signals Extract DPO preference pairs and normalized rewards from council verdicts for evaluator and training workflows.

支持功能：自定义角色、快速/标准/深度模式、可选审计 日志、打包的Hermes技能、OpenAI兼容的提供商支持和stdio MCP 运输。

快速入门

安装

pip install "hermes-council @ git+https://github.com/Ridwannurudeen/hermes-council.git"

对于RL/评估器的使用：

pip install "hermes-council[rl] @ git+https://github.com/Ridwannurudeen/hermes-council.git"

配置Hermes代理

将MCP服务器添加到 ~/.hermes/config.yaml:

mcp_servers:
  council:
    command: python
    args: ["-m", "hermes_council.server"]

hermes-council-server 也作为控制台脚本安装。这 python -m 建议使用表单，因为它即使在Python用户脚本目录下也能工作 没开 PATH.

您还可以使用Hermes Agent自己的CLI以交互方式连接服务器：

hermes mcp add

hermes mcp add/list/remove/test 写入相同内容 mcp_servers 输入 ~/.hermes/config.yaml，因此任一路径都会生成等效的配置。

设置一个提供程序密钥：

export OPENROUTER_API_KEY=your-key-here

PowerShell：

$env:OPENROUTER_API_KEY = "your-key-here"

然后重新启动Hermes Agent或运行 /reload-mcp.

安装Hermes技能

hermes-council install-skills

这将技能定义复制到 ~/.hermes/skills/council/.

无Hermes试剂的烟雾测试

python -m hermes_council.server

服务器通过stdio与MCP通信，因此它等待JSON-RPC消息。使用这个 主要是验证模块入口点是否干净导入。

直接使用评估器

import asyncio
from hermes_council.rl.evaluator import CouncilEvaluator

async def main():
    evaluator = CouncilEvaluator(model="nousresearch/hermes-3-llama-3.1-70b")
    verdict = await evaluator.evaluate(
        content="Ship the migration after tests pass.",
        question="Is this deployment plan safe enough?",
        criteria=["safety", "rollback", "evidence"],
    )
    print(verdict.confidence_score)
    print(evaluator.normalized_reward(verdict))

asyncio.run(main())

工具

Hermes Agent使用服务器前缀公开MCP工具。使用上面的配置 运行时名称为 mcp_council_council_query, mcp_council_council_gate等等。

栅极输出

{
  "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"]
  }
}

理事会模式

建筑

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

服务器使用与OpenAI兼容的异步客户端。它首先尝试JSON模式，然后 当提供者拒绝时，回退到文本解析 response_format.

证据模型

evidence_search=true 在角色调用之前运行检索。

安全边界：

• 仅 http 和 https 获取URL。
• 本地主机、私有IP、链接本地IP、多播、保留和未指定

IP在获取之前被阻止。

• 集 COUNCIL_EVIDENCE_SEARCH=0 在静止时禁用DuckDuckGo搜索

允许获取提供的公共URL。

配置

API的关键优先级是：

COUNCIL_API_KEY > OPENROUTER_API_KEY > NOUS_API_KEY > OPENAI_API_KEY

人物角色

自定义角色

创建 ~/.hermes-council/config.yaml:

personas:
  security_analyst:
    tradition: "Adversarial security thinking"
    system_prompt: "You are a security analyst. Evaluate every claim for attack vectors, failure modes, and adversarial scenarios."
    scoring_weights:
      threat_assessment: 0.4
      evidence: 0.3
      rigor: 0.3
    tags: ["security", "adversarial"]

自定义角色与默认角色合并。使用相同的名称覆盖默认值。

项目布局

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

发展

git clone https://github.com/Ridwannurudeen/hermes-council.git
cd hermes-council
pip install -e ".[dev]"
python -m pytest -q

有用的检查：

python -m pytest -q
python -m ruff check src tests
python -m pytest --cov=hermes_council --cov-report=term-missing -q
python -m pip wheel --no-deps . -w dist

验证

测试套件包括：

• MCP stdio服务器通过启动 python -m hermes_council.server
• 所有委员会工具的工具发现
• Hermes兼容无钥匙故障行为
• 门判决语义
• 证据检索与专用网络URL屏蔽
• 从轮子上组装技能装置
• 审计日志写入
• 自定义角色加载
• JSON模式和回退解析路径

诚实的限制

• 实际模型支持的判决需要真实的提供者密钥。
• DuckDuckGo HTML搜索可以更改；提供的URL比搜索更可靠

结果。

• verified_sources 证明的是可检索性，而非真实性。仲裁员仍在权衡

证据。

• 服务器仅支持stdio MCP。此仓库中没有托管的HTTP服务。
• 该委员会增加了延迟和令牌成本。使用 fast 常规飞行前模式。
• JSON字段的模型合规性取决于提供者/模型行为，不过

实现了回退解析。

路线图

• \[\]添加一个仅在存在CI机密时运行的实时提供程序冒烟工作流。
• \[\]为证据片段添加来源排名和引用质量评分。
• \[\]为极低延迟门添加紧凑的仅判决模式。
• \[\]添加可选的HTTP/可流式传输MCP。
• \[\]为Hermes代理商计划审查和差异审查会议添加一流示例。
• \[\]添加基准装置，将理事会审查与单一模型批评进行比较。

起源

该项目是为了回应以下反馈而建立的 爱马仕代理商PR#848, 其中，对抗性委员会概念被提出作为核心子系统。这 建议将其重建为外部MCP服务器，以避免使用核心工具 注入、提供者绕过、隐藏的LLM成本和脆弱的解析。

后续集成PR在hermes代理中提出了一个注释配置存根 (诺斯研究/爱马仕代理#1972) 是 2026年5月11日关闭 --维护人员不会捆绑第三方MCP 服务器引用 cli-config.yaml.example 或 optional-skills/ 避免 支持一个社区服务器而不是其他社区服务器。通过以下方式独立安装 快速入门 以上；服务器被设计为以这种方式运行。

贡献

• 尽可能保持MCP工具输出的结构化和向后兼容。
• 为每个新的工具字段或运行时边界添加测试。
• 使用 python -m hermes_council.server 在文档和集成示例中。
• 在OpenAI兼容的客户端设置后保持特定于提供者的行为。
• 在打开PR之前，进行测试、皮棉、覆盖和车轮包装检查。

许可证

MIT。看 许可证.