微软 agent-hooks CTK 实测：8 框架演示，3 行合规表

微软 agent-hooks 的发布稿声称，同一退款场景在八个框架上跑出完全一致的 20 行决策流。但仓库里同时发布的合规测试套件（CTK）和声明表，只列了三行。我装上 SDK 亲自跑了一遍 CTK，又逐字读了声明文件，差距比发布稿暗示的要大。

跑一遍 CTK

CTK 没有命令行入口，是一个 Python 模块，四行代码就能调起来：

from agent_hooks.ctk import load_vectors, run_vectors
from agent_hooks.ctk.reference import ReferenceHarness

vectors = load_vectors()
results = run_vectors(ReferenceHarness, vectors)
print(len(results), sum(r.status == "pass" for r in results))

**能力门控（capability gating）** 是合规测试套件里一个容易被忽略但决定结论的设计：宿主实现先在声明文件中列出自己支持的能力集合（比如 `incremental_output`），CTK 根据这份声明对测试向量做筛选，只运行宿主声明范围内的向量，范围之外的标记为 `skip` 而非 `fail`。这种机制对实现方友好——它不惩罚未实现某能力的宿主，但代价是“通过率”这一指标的含义被稀释：分母不同的人算出不同的结果，一个不支持增量中介的宿主天然不可能失败在那部分向量上。对采购方来说，正确的问题不是“通过率多少”，而是“被跳过的向量覆盖了哪些契约行为，这些行为我的场景是否需要”。只读通过率数字，很容易把“未测试”误读成“已通过”。
# 73 69

在 agent-hooks-sdk==0.1.0b2、Python 3.13 下，结果是 73 个向量、69 通过、4 跳过、0 失败，耗时 0.37 秒。不需要模型、不需要网络、不需要 API key，是整个技术栈里最容易复现的部分。

四个跳过项才是重点，它们不是失败：

AH-CTK-110  skip  incremental mediation: ...
AH-CTK-111  skip  incremental mediation: ...
AH-CTK-112  skip  incremental mediation: ...
AH-CTK-113  skip  incremental mediation: ...

原因字段是 missing capabilities: ["incremental_output"]。CTK 是能力门控的——宿主先声明自己能做什么，声明之外的向量会被跳过而不是判失败。把这四个拿掉，整个流式/增量部分的契约就没有被测试。

这个设计站得住脚，仓库也明说了。conformance/CLAIMS.md 把“合规”定义为通过 CTK 中“适用于宿主声明范围”的全部向量，并要求带增量中介能力的宿主必须声明 incremental_output。但作为采购方而不是规范作者来读，“通过 100% 适用向量”和“通过 100% 向量”在新闻稿里听起来一样，实际完全不是一回事。

合规表只有三行

本次运行时的完整声明表如下：

宿主	适配器	报告
reference-agent（仓库内）	0.1.0	我的运行：69/73，4 个能力门控跳过
microsoft/agent-framework（Python）	core 1.13.0	47/51 通过，4 个能力门控跳过
agent-control-spec（Rust）	rust@0.1.0-alpha.5	47 向量语料上 46/47，1 跳过

三行。发布稿里点名的八个框架中，LangGraph、OpenAI Agents SDK、Semantic Kernel、LlamaIndex、CrewAI、Claude Agent SDK 六个没有任何文件记录。

我先找适配器再看声明，Python 包印证了这一点：在整个 agent_hooks 包里 grep langgraph、langchain、openai、crewai、llama_index、semantic_kernel、claude，零命中。Python 端唯一随包发布的宿主绑定是 agent_framework 里的 create_agent_hooks_middleware。今天想在 LangGraph 或 OpenAI Agents SDK 循环里用 agent-hooks，得自己写适配器——四方法 harness 接口就是接口，只是没人替你写。

harness 接口 在这里指的是契约与具体宿主之间的适配层：它把 agent-hooks 的拦截点（如 pre_tool_call）映射到目标框架实际的控制流上——在哪个函数调用前插入检查、用哪段状态对象传递决策、异常或返回值如何转成阻断信号。文章提到“四方法 harness 接口”，说明接口本身很小，但真正的工作量不在实现这四个方法，而在于搞清目标框架有没有一个稳定、可插入的接缝。这就是适配器迟迟未出现的原因：接口可以照抄，接缝却可能需要框架上游先改代码。没有适配器，契约只能停留在演示里，落不到真实循环中。

ToolNode 与 before_tool_call 钩子 是理解 LangGraph 那条 issue 的关键。LangGraph 把模型的工具调用路由进 ToolNode 节点执行，模型的决策（调用哪个工具、传什么参数）在进入节点前已经生成，节点内部负责真正执行。中间件式的 before_tool_call 钩子需要在这个执行前的缝隙里拿到控制权，才能检查、修改或阻断调用。LangGraph 目前没有一个稳定的、契约化的一等钩子覆盖这个缝隙，所以 agent-hooks 这类依赖“执行前拦截”的契约在这里缺少落脚点。issue#8102 请求的正是补上这个接缝——在它被接受之前，任何声称的兼容都只能靠框架外部的包装代码模拟，稳定性无法保证。

不算丑闻，但这就是全部真相

这里面没有不诚实的地方，我想把原因说清楚。

发布稿说的是“我们让同一场景跑了八个框架”，这是真的。微软写了一套演示，接到八个宿主上，拦截契约本身足够宿主无关，保护代码可以平移。它没说的是：随包发布的 SDK 实际只绑定了一个。演示是微软的代码跑在八个宿主上；合规声明是每个宿主各自要提 PR 归档的产物。仓库说得很直白：维护框架、想让合规报告上有自己名字的，harness 接口只有四个方法，微软愿意一起做集成。

公平。但这份邀请目前八个里有六个没接受。

仓库对局限同样坦白，我宁可引用也不转述：“合规声明不是安全认证……不测试对抗性绕过，不保证生产代码路径与 harness 一致。”MAF 的声明还落后一个版本——引的是 commit 4b1afd9052 的 core 1.13.0，而我安装时 1.21.0 已是当前版本；声明钉在 51 向量语料上，插件现在加载的是 73 个。声明会老化。

线索藏在 LangGraph 自己的 issue 里

想具体感受“八个框架”的实际覆盖，别读发布稿，去读 langgraph#8102：2026-06-16 开的，至今 Open，无人认领，标着 external。

LangGraph 把模型的工具调用路由进 ToolNode（_run_one / _arun_one）再执行。实践中没有一个简单的一等 before_tool_call 钩子，能用稳定契约在调用执行前拦截、检查、阻断或修改。

这正是在请求 agent-hooks 整套模型赖以成立的那个接缝。它开了四个月无人回应。一个连执行前工具接缝都还停留在 RFC 阶段的框架，没有采纳一个第四个拦截点叫 pre_tool_call 的契约——不管演示里演了什么。

实操建议

三件事，按顺序：

1. 把 conformance/CLAIMS.md 当作受支持宿主列表，而不是发布稿。就一张表，点名 commit，是仓库自己对“受支持”的仲裁者。
2. 采纳前自己跑一次 CTK。四行代码、亚秒级，能告诉你你的宿主实际覆盖了契约的哪部分。如果 4 个向量跳过，你就知道哪类问题还没答案。
3. 你的框架不在表里，诚实的解读是“规范可移植，适配器没写”。这是个真实决策，不是走形式——适配器是裁决契约与你循环实际控制流相遇的地方。

契约本身做得不错，带能力门控、按参与方出报告的合规机制，比多数治理类发布要诚实。错误在于把“八个框架”当成兼容性声明来读。它是一次演示。