agent-gate — fail-closed quality gate + hash-chained receipt ledger for agent work (stdio via PyPI)

agent-gate

一个 MCP 服务，让 AI Agent 在宣称“完成”之前先对自己的工作进行把关：先执行确定性检查，再进行独立的先反驳式审查，最后生成防篡改的如实回执。

让 Agent 给自己的作业打分，会产出低质量结果。agent-gate 将这套规范转化为 Agent 必须通过的工具：一个失败即关闭的检查清单，以及一个仅追加、哈希链式回执账本。它将 Fleet Mode 这一 Agent 编排准则做成了可运行的工具。回执胜过炒作，并由数据结构强制保障。

🧩 这是由五个代码库构成的成本治理技术栈中的一层，用于高效运营 AI Agent；bow 是旗舰项目，可在生产环境中运行每一层。

agent: "done!"  ->  verify_gate(evidence)  ->  { passed: false, blocking: ["independent_refute_review", "no_secrets"] }

为什么需要

Agent 系统中代价高昂的故障往往悄无声息：模型更新导致输出质量下降、改动暗中破坏工作流、Agent 在工作有误时却宣称成功。解决办法不是换一个更聪明的模型，而是设置一道 Agent 无法靠说辞蒙混过关的关卡：

• 失败即关闭。 只有明确为真的检查才算通过。缺少证明不等于证明通过。（这类似于晋级关卡，而非非正式检查。）
• 防篡改回执。 每项决策都会记录为 (decision, metric, value, verdict)，并链接到 sha256 链中。编辑或删除任何过往回执，verify_chain() 都会返回 false。如实记录由结构强制保障，而非依赖良好意图。
• 默认由人工把关。 “任何不可逆或对外的操作都获得了人工批准”是一项必需检查。Agent 起草，人类批准。

工具（通过 MCP）

工具	功能
gate_checklist(name="ship")	返回 Agent 在宣称完成前必须通过的检查清单。
verify_gate(evidence, name="ship")	以失败即关闭的方式评估证据，并返回 {passed, blocking}。
record_receipt(decision, metric, value, verdict)	追加一条如实的哈希链式回执，并返回该回执。
read_receipts()	返回所有回执，以及链是否完整。

默认的 ship 关卡体现了 Fleet Mode：deterministic_checks_pass、independent_refute_review、no_secrets、human_gated_if_irreversible、honest_receipt_logged。

安装并接入 MCP 客户端

pip install mcp-agent-gate   # or: pip install -e . (from source)

将其添加到 MCP 客户端（Claude Desktop / Claude Code）的配置中：

{
  "mcpServers": {
    "agent-gate": { "command": "python", "args": ["-m", "agent_gate.server"] }
  }
}

现在，Agent 可以在告诉你工作已完成前调用 verify_gate(...)，你也能获得一份防篡改记录，了解它做出的决策。回执会持久化到 ~/.agent-gate/receipts.jsonl（可通过 AGENT_GATE_LEDGER 覆盖）。

直接使用（无需 MCP 客户端）

from agent_gate.gate import DEFAULT_SHIP_GATE
from agent_gate.ledger import Ledger

res = DEFAULT_SHIP_GATE.evaluate({
    "deterministic_checks_pass": True,
    "independent_refute_review": True,
    "no_secrets": True,
    "human_gated_if_irreversible": True,
    # honest_receipt_logged missing  ->  fail-closed
})
print(res.passed, res.blocking)   # False ['honest_receipt_logged']

led = Ledger("receipts.jsonl")
led.append(decision="ship v0.1", metric="tests", value="pass", verdict="shipped")
print(led.verify_chain())         # True  (until someone edits the log)

设计

• 经过测试、仅依赖标准库的核心。 agent_gate/gate.py（默认拒绝的检查清单）和 agent_gate/ledger.py（哈希链式收据）仅使用标准库：易于快速阅读，也易于信任。agent_gate/server.py 是基于它们构建的轻量 MCP 适配器（唯一的运行时依赖：mcp）。
• 测试通过 Python 3.11–3.13 版本（见 CI）。 MCP 工具通过实际调用进行测试，而不只是导入。

测试

pip install -e ".[dev]" && python -m pytest -q

演示

亲自运行：PYTHONPATH=. python3 examples/demo.py

------------------------------------------------------------
1. Agent claims done — but two checks are missing
------------------------------------------------------------
{
  "passed": false,
  "blocking": [
    "human_gated_if_irreversible",
    "honest_receipt_logged"
  ]
}

------------------------------------------------------------
2. Agent satisfies all five checks
------------------------------------------------------------
{
  "passed": true,
  "blocking": []
}

------------------------------------------------------------
3. Record a hash-chained receipt
------------------------------------------------------------
{
  "seq": 1,
  "decision": "ship v0.1",
  "verdict": "shipped",
  "hash": "015202a168512f15..."
}
{
  "seq": 2,
  "decision": "deploy",
  "verdict": "approved",
  "hash": "9533d304d4dd07e5..."
}

------------------------------------------------------------
4. Verify the chain — edit receipts.jsonl to see this flip to False
------------------------------------------------------------
chain_intact: True

本仓库也对自身进行门控

agent-gate 致力于避免发布未经验证的工作，因此仓库也以同样的标准要求自身：

• 覆盖率门控测试矩阵 — ci.yml 在 Python 3.11–3.13 版本上运行 pytest；如果行覆盖率低于阈值（当前覆盖率为 97%），构建就会失败。
• CodeQL — 静态分析（security-extended）会在每次推送、PR 和每周运行；发现的问题会显示在 Security 选项卡中。
• 锁定供应链 — 每个 GitHub Action 都锁定到完整的提交 SHA；Dependabot 会保持这些锁定项和 Python 依赖项为最新。
• 分支保护 — 合并前，main 分支要求 CI 和 CodeQL 检查通过。
• 漏洞披露政策 — 请参阅 SECURITY.md。

贡献

请参阅 CONTRIBUTING.md。

关于

由 Jeff Otterson (Jott2121) 构建。agent-gate 将 bow（一个完全由 Claude 驱动的自主幕僚长 Agent）中的门控规范，以及 Fleet Mode 理念付诸实践。同系列的相关项目：rag-guard 和 agent-cost-attribution。采用 MIT 许可证。

配套工具

sabot 是这一理念的测量工具。agent-gate 为 Agent 工作流添加默认拒绝的门控；sabot 则在运行中的 LangGraph、CrewAI 和 AutoGen 流水线中植入受控故障，并测量门控和此类审核阶段是否确实触发。在三个生产级框架中，自检检测率的中位数为 16.7%，并提供预先注册的规范、Apache-2.0 测试框架，以及公开发布的全部原始跟踪记录。