Agent Governance Toolkit v4 策略语言移除指南ACS v5 单一契约迁移、渐进式绞杀与零基线 Ratchet【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit导读本文围绕 Agent Governance ToolkitAGT中「v4 策略语言移除v4 policy-language removal」这一核心技术演进展开系统讲解 AGT 如何将遗留的 v4 意图式策略语言GovernancePolicy、PatternType、PolicyInterceptor等逐步淘汰使 ACSv5策略层成为工具包中唯一的策略契约。你将掌握v4 与 v5 的符号级对应关系、从governance.yaml时代走向 AGT-MANIFEST-1.0 清单时代的字段处置方法、scripts/check_v4_ratchet.py严格棘轮ratchet机制的实现原理与命令行用法以及从阶段 0 到阶段 6 的完整分阶段迁移路径。本文以 v4-removal.md 为骨架结合仓库中scripts/check_v4_ratchet.py、scripts/v4_ratchet_baseline.json、agent-governance-python/agt-policies/src/agt/cli/下的迁移工具源码等证据展开。对 v4 用户而言这是一次破坏性变更breaking change迁移路径是单向的v4 工程只能转换为 v5 ACS 清单无法回退。一、为什么移除 v4 策略语言AGT 正在移除遗留的 v4 策略语言目标很明确让 ACSv5策略层成为工具包中唯一的策略契约。v4 的构造只允许存活在一个地方——单向迁移工具one-way migration tool内部该工具把 v4 工程转换为 v5 ACS 清单。从仓库中的 ratchet 脚本文档可以看出这一战略定位的完整表述check_v4_ratchet.pyPhase 0 of removing the legacy v4 policy language so the ACS (v5) policy layer is the only policy contract in the toolkit.这意味着策略契约收敛不再同时维护两套策略语言避免语义漂移、双份维护成本和审计复杂度单向迁移v4 构造仅存于迁移工具运行时模块只接受 ACS 与 AGT 清单破坏性变更v4 用户必须升级且升级路径不可逆。二、什么是 v4 策略语言符号清单与 v5 对应关系文档给出了完整的 v4 符号清单明确每个符号的「原住地Home」与「v5 替代品Replacement」。下表是 v4 用户定位升级目标的核心地图符号原住地Homev5 替代品GovernancePolicy、PatternTypeagent_os/integrations/base.pyACS manifest 加AgentControlPolicyInterceptor、ExecutionContextagent_os/integrations/base.pyHostSessionoverAgentControlViolationCategory、PolicyCheckResultagent_os/policies/decision.py原生 v5 结果与错误契约PolicyDocument、PolicyAction、CedarBackendagent_os/policies/ACSpolicies.type: cedar与原生清单governance_to_acs_manifestagt/policies/bridge.py仅迁移工具使用governance_to_documentagent_os/policies/bridge.py已删除get_runtime_bridge、AdapterRuntimeBridgeagent_os/integrations/_v5_runtime_bridge.pyHostSessionto_v4_check_resultagt/policies/result.py已删除运行时governance.yaml解析私有agt.cli迁移器迁移时一次性扁平化flatten仓库中的 ratchet 脚本check_v4_ratchet.py以UNAMBIGUOUS_SYMBOLS冻结集合的形式把这些 v4 标识符逐一登记为「无歧义 v4 符号」供全局计数。脚本中还包含更多 v4 时代的辅助符号例如from_cedar、discover_policies、aca_config_from_policy、docker_config_from_policy、hyperlight_config_from_policy、mxc_config_from_policy、nono_config_from_policy、PolicyTemplates、compose_policies、override_policy等——它们同样是 v4 扫描范围的一部分。三、v4 的唯一合法栖身地单向迁移工具v4 策略语言只允许存活在迁移工具内部。棘轮机制通过**显式允许清单allowlist**豁免迁移模块而非豁免整个目录允许清单包含agent-governance-python/agt-policies/src/agt/cli/migrate.py及其同级模块后续将演进为独立的agt-v4-migrate发行包及其测试。从仓库实际结构看迁移工具的载体已落地为agent-governance-python/agt-policies/src/agt/cli/migrate.py—— 主迁移命令agent-governance-python/agt-policies/src/agt/cli/_migrate_bridge.py—— 冻结的 v4 运行时桥differential test 的参照实现agent-governance-python/agt-policies/src/agt/cli/_migrate_re2.py—— RE2 校验辅助agent-governance-python/agt-policies/src/agt/cli/_migrate_resolution/—— 迁移期governance.yaml解析器discover.py、merge.py、build.py、scope.py、errors.py对应文档 Phase 4 中「resolver 及其契约、测试只存活于agt.cli._migrate_resolution」的表述agent-governance-python/agt-policies/src/agt/cli/__main__.py—— CLI 入口。迁移工具的语义约束只读一次读取 v4 工程一次输出扁平化的 ACS 清单加 bundles运行时不受影响运行时模块只接受 ACS 与 AGT 清单组合用原生语法策略组合使用原生 ACSextends不再由迁移工具合成运行时策略。四、分阶段移除计划内部绞杀 原子化公开破坏性发布移除以「内部绞杀者strangler」模式运行最后通过一次原子化的公开破坏性发布完成切换。六阶段全景如下阶段内容关键产出0语义清单semantic inventory与跨 Python / Rust / TypeScript 的 CI 棘轮scripts/check_v4_ratchet.pyscripts/v4_ratchet_baseline.json基线1定义原生 v5 结果、错误、审计、类型化清单与适配器强制契约审计GovernancePolicy每个字段AgentControl原生契约、InterventionPointResult、PolicyViolationError2从 v4 运行时桥提取 ACS 原生HostSession隔离并加固迁移翻译器HostSession拥有快照构建器、计数器、原生干预点调用3将所有运行时桥消费者迁移为「绿色纵向切片green vertical slices」并带测试与示例17 个框架适配器切换至NativeAdapterRuntimeHostSession4迁移非适配器消费者与遗留策略子系统删除运行时governance.yaml解析移除运行时治理文件夹发现resolver 迁入agt.cli._migrate_resolution5重写 Rust 与 TypeScript 的 v4 表面修复包构建RustFrameworkGovernanceAdapter接受原生契约Mastra 委托AgentControl.runTool6原子化移除所有桥、v4 结果转换与再导出把棘轮收紧到零删除运行时桥、GovernancePolicy契约、兼容结果/决策类型基线归零阶段 0语义清单与棘轮scripts/check_v4_ratchet.py是阶段 0 的核心交付物它按文件对每个存活的 v4 符号做清单统计并强制执行严格棘轮任何变更不得新增 v4 用法、v4 标记不得移入新文件、每个符号的计数不得上升。脚本的检测能力与 check_v4_ratchet.py 的 docstring 一致非常细致Python 检测基于 AST 且感知 import普通字符串和注释永远不计入避免误计数计数对象类与函数定义、别名导入及其使用、关键字与参数名、__all__条目、复合字符串注解、以及被动态导入 /getattr/mock.patch使用的语义字符串常量——因此计数不可能在未真正删除的情况下下降歧义名处理与无关代码冲突的名字ExecutionContext、PolicyEvaluator只有在「从合格 v4 模块绑定」「通过 v4 模块别名访问」或「在规范 v4 文件中定义并使用」时才计数相对导入会按当前模块解析从而不会误伤外来同名代码Markdown 要求对歧义名需要限定 v4 上下文才计数失败闭合任何无法解码或解析的 Python 文件直接导致 gate 失败fail closedRust / TypeScript使用标识符边界identifier-boundary的 token 匹配Markdown 与规范层从统一词表one vocabulary扫描每个 YAML / YML / JSON 文件都要检查完整的 v4PolicyDocument与PolicyDefaultsschema并带显式的 ACS、Kubernetes、AgentMesh 信任策略排除项governance.yaml/governance.yml无论内容如何都计数从而让文档、spec 与策略数据的清除义务对零门zero gate可见结构性检查窄范围的结构检查还能捕获「改名后的意图策略解释器」——即把 blocked patterns、工具列表、预算、pattern 模式组合在一起的改名实现。命令行用法与 check_v4_ratchet.py 一致另支持--json输出python scripts/check_v4_ratchet.py # 对照基线执行 gate python scripts/check_v4_ratchet.py --report # 查看清单不执行 gate python scripts/check_v4_ratchet.py --json # 机器可读输出 python scripts/check_v4_ratchet.py --update-baseline # 在真实减少后更新基线 python scripts/check_v4_ratchet.py --update-baseline --allow-baseline-increase # 显式放行扫描语义变更scripts/v4_ratchet_baseline.json是提交到仓库的基线文件。--update-baseline拒绝批准计数上升除非显式传入--allow-baseline-increase仅用于刻意的扫描器语义变更。迁移允许清单会被登记与报告但永远不会计入棘轮计数。该 gate 及其单元测试与 lint 通过.github/workflows/v4-removal-ratchet.yml在每次 Pull Request 上运行。仓库中的 test_check_v4_ratchet.py 即该 gate 的单元测试。阶段 6 的最终 gate 会把非迁移总量含规范性 spec驱动到零。阶段 1原生契约AgentControl构造与清单表示AgentControl.from_path(str(...))是规范的运行时构造函数接收文件系统路径。路径自带其父目录作为来源信息provenance因此相对的 bundle、data、prompt、Cedar 与extends引用都相对清单解析而不是相对当前工作目录。其他构造方式AgentControl.from_native—— 清单已在内存中时使用AgentControl.from_url—— 远程场景AgentControl.from_manifest_chain—— 分层layered场景。解析后的清单是AGT-MANIFEST-1.0 的无损表示执行结构校验并保留 policy、tool、annotator、resolver 与 host extension 字段。它不接受意图级字段max_tokens、allowed_tools、blocked_patterns也从不合成策略或绑定。适配器兼容性由独立的AdapterManifestContract预检负责。静态预检要求已解析的清单因为extends父级可能提供必需的干预点或工具。关于limits段有一个重要安全原则模型保留 AGT 的limits段但运行时构造会拒绝它直到 Python SDK 能够强制执行这些值——静默接受一个无法强制执行的安上限是不允许的。评估结果与错误契约AgentControl.evaluate_intervention_point(...)返回不可变的InterventionPointResultverdict携带decision、reason、message、transform、evidence、result_labels结果本身携带transformed_policy_target、transformed_policy_target_applied、input_identity、enforced_identity审计信封使用 schemaagt.policy_evaluation.v1ACS 目前不在InterventionPointResult上暴露policy_id或rule_id因此这两个字段不出现在契约中调用方不得从reason_code推断它们策略作者编写的message仍属于受限审计细节restricted audit detail。错误契约方面PolicyViolationError.from_evaluation_result(...)会发出稳定的、消毒后的公开消息而不是把策略内容或用户内容复制进异常文本——这直接服务于防止敏感信息泄漏。现有的AgentControl(...)、evaluate_intervention_point(...)、EvaluationResult在阶段 2 之前仍作为临时的桥接专用兼容表面存在阶段 6 会整体移除。适配器强制契约Adapter enforcement contract关注点原生契约必需干预点每个适配器都声明它们执行前检查运行时契约。缺少必需干预点是构造错误绝不是运行时的 allow 回退工具目录manifest要求静态toolshost_dynamic由宿主同步optional不施加目录要求Transform每个适配器声明可应用 transform 的干预点共享适配器会话在转发 payload 前应用它审批ApprovalAgentControl拥有 resolver 与超时行为。给定运行时的适配器不能再接受竞争性的 resolver 配置预算Budgets尝试调用即消耗工具调用预算包括被拒绝与失败的尝试。会话计数器位于适配器会话中而非AgentControl运行时共享当宿主 dispatcher 与审批回调是线程安全时一个运行时可以共享。会话快照与计数器绝不停留在运行时上失败方向非法清单、缺失必需绑定、dispatcher 错误、审批错误全部失败闭合fail closed。原生路径不会把未知干预点或工具改写为 allowGovernancePolicy字段处置表v4 字段v5 处置namemetadata.nameversion迁移期间仅作metadata.policy_versionmax_tokens基于快照 token 计数的 ACS 预算策略max_tool_calls基于尝试调用次数的 ACS 预算策略。迁移期间零保持为全部拒绝deny-allallowed_toolsACStools目录或 host-dynamic 目录契约。空的 v4 列表迁移为无 allowlistblocked_patterns按需绑定到输入、输出与工具参数的显式 Rego 策略require_human_approvalEscalate 判定加清单approval与运行时 resolverconfidence_threshold绑定在post_model_call的策略timeout_seconds宿主执行上限而非策略语言drift_threshold宿主 annotator 或策略输入由适配器显式选择log_all_calls宿主审计配置checkpoint_frequency宿主编排配置max_concurrent宿主并发配置backpressure_threshold宿主并发配置detection 模块字典宿主安全模块配置而非清单策略detection宿主模块启用与强制执行动作迁移工具必须要么精确翻译每个策略字段要么拒绝转换并给出人工复核发现manual-review finding。仅宿主管辖的字段必须显式移入宿主配置不得静默丢弃。阶段 2提取边界HostSession现在拥有单个会话的SnapshotBuilder、计数器与原生干预点调用在执行前预留尝试的工具调用使被拒绝与失败的尝试也消耗预算在post_model_call之后记录模型 token只序列化计数器变更AgentControl保持无会话状态在阶段 1 回调线程安全契约下可共享。v4 运行时桥把快照构建与评估委托给原生会话自身只保留v4 翻译、结果转换、宿主预算回退、审批回退、以及两处默认允许改写default-permit rewrites。现有适配器暂时禁用原生计数器计费避免在阶段 3 脱离ExecutionContext之前重复计数。单向GovernancePolicy翻译器位于agt.cli下没有运行时导入路径。它接受精确字面量字段精确的PatternType.SUBSTRING、PatternType.REGEX、PatternType.GLOB形式。以下情况一律拒绝迁移动态表达式、宿主专属设置、非法 pattern、不支持的字段、以及已存在的输出。生成的清单在原子写入前用validate_manifest校验。差分测试将每个受支持构造与冻结的运行时桥对比确保默认值与边界语义在过渡期不漂移。细节要点REGEX 与 GLOB 使用 OPA 的 Go RE2 校验器仓库中对应实现见agent-governance-python/agt-policies/src/agt/cli/_migrate_re2.pyGLOB 使用 RE2 的\z结束锚点而非 Python 不支持的\Z构造函数与治理链迁移都拒绝覆盖已存在的清单、bundle 与备份。阶段 3适配器切换17 个桥接框架适配器现在接受公开的原生runtime参数并把 model、tool、stream、output 干预点路由到NativeAdapterRuntime与HostSession。涉及框架A2A、Agent Shield、Anthropic、AutoGen、Bedrock、CrewAI、Gemini、Google ADK、Guardrails、LangChain、LlamaIndex、MAF、Mistral、OpenAI、PydanticAI、Semantic Kernel、Smolagents。它们不再通过AdapterRuntimeBridge或BridgeResult导入与评估唯一残留的_v5_runtime_bridge依赖是临时策略兼容边的构造函数选择器。特殊命名说明Agent Shield 使用agt_runtime参数名因为其既有位置参数runtime指的是 Agent Shield SDK 对象。原生拒绝native denials会把evaluation_result与agt.policy_evaluation.v1审计记录附加到PolicyViolationError临时策略边仍附加check_result由一个共享结果 dispatcher 选择。两条路径中 transform 均为原生对象。运行时拥有审批配置适配器可以省略approval_resolver或重复相同回调以支持过渡代码但不同回调会在构造时被拒绝。旧policy与私有_runtime参数仅用于让开发树在阶段 6 的公开破坏性切换前保持绿色。便捷包装器也接受runtime但其策略路径不是原生默认会随兼容桥一起移除。OpenAI Agents SDK 与 LangGraph 现在暴露原生运行时钩子路径同时在宿主侧保留 checkpoint、handoff、审计与包装行为。阶段 4运行时清理运行时治理文件夹发现已被移除resolver、其契约与测试只存活于agt.cli._migrate_resolution仓库中对应discover.py、merge.py、build.py、scope.py、errors.pyAgentControl不再接受resolution_rootagt.manifest_resolution不对外公开OPA 场景测试工具不再从governance.yaml合成运行时策略原生组合使用 ACSextendsRust 核心与 SDK 奇偶校验 fixtures 不再暴露迁移专用的runtime_error:resolution_*变体迁移命令私有保留等价诊断用于报告生成OpenAI Agents SDK 钩子在给定runtime时通过NativeAdapterRuntime评估输入、工具调用、工具结果与输出LangGraph 原生评估节点状态与工具调用并对运行时清单加已注册工具哈希做指纹fingerprint非策略语义handoff 限制、checkpoint 元数据、节点包装、审计事件仍归宿主所有。阶段 5语言与打包重写Rust 的FrameworkGovernanceAdapter现在接受原生AgentControl、Manifest与显式FrameworkHostConfig已移除的本地策略与 pattern 类型不再导出遗留形状的 YAML 直接清单校验失败不再做进程内翻译Mastra 包现在依赖 Node ACS 包每个工具调用都委托给AgentControl.runTool信任与防篡改审计仍是 Mastra 中间件策略决策、transform、审批与工具目录全部来自 ACS 清单合并后的 Python core wheel 声明依赖agt-policies因为强制包含原生适配器模块wheel 检查门会构建两个产物、校验依赖元数据、确认原生会话/运行时模块与迁移 Rego 资源已打包并拒绝公开的manifest_resolution包。阶段 6原子化移除公开兼容切换会移除运行时桥、中心GovernancePolicy契约、兼容结果与决策类型、遗留策略加载器与后端、运行时文件夹解析。框架适配器现在要求原生 ACS 运行时原生拒绝使用规范PolicyViolationError并保留结构化PolicyEvaluation。旧意图策略字段不再有运行时实现Haystack 集成的本地检查器等框架本地策略解释器被删除而非改名转换支持只保留在agt.cli下单向迁移命令AgentMesh Wire Protocol 策略引擎是独立保留的产品其 Python 实现与 TypeScript、Go、.NET 移植版使用 AgentMesh 规则 schema 与跨语言奇偶校验测试不是被移除意图策略契约的适配器也不在这次迁移范围内最终棘轮基线在迁移允许清单之外归零结构检查同时检测改名的意图策略解释器并区分保留的 AgentMesh 规则文档与被移除的策略数据。五、迁移实操路径v4 用户该怎么做结合文档与仓库中的迁移工具agent-governance-python/agt-policies/src/agt/cli/v4 用户的推荐路径如下盘点现状先运行python scripts/check_v4_ratchet.py --report查看当前 v4 符号的完整清单确认工程中所有GovernancePolicy、PolicyDocument、governance.yaml等 v4 构造的位置与数量转换策略意图对照上文「GovernancePolicy字段处置表」把每个字段映射到 v5 目标——策略语义进 ACS 清单metadata.name、policies.type: cedar、显式 Rego宿主管辖的字段预算、并发、超时、审计、checkpoint、backpressure移入显式宿主配置执行单向迁移通过agt.cli的迁移命令见migrate.py与__main__.py读取 v4 工程生成扁平 ACS 清单与 bundles只支持精确字面量字段与SUBSTRING/REGEX/GLOB三种 pattern 形式动态表达式与宿主设置会被拒绝并要求人工复核验证产物确认生成的清单通过validate_manifest校验、没有覆盖既有清单与备份GLOB pattern 使用的是 RE2\z锚点而非 Python\Z需注意 pattern 写法差异切换适配器框架适配器传入原生runtimeAgent Shield 用agt_runtime模型、工具、流与输出干预点自动走NativeAdapterRuntime与HostSession回归与收敛利用差分测试确保默认值与边界语义与冻结的运行时桥一致最终配合阶段 6 的原子化发布把棘轮基线收敛到零。六、给 v4 用户的兼容性提示这是一次破坏性变更阶段 6 之后运行时不再提供任何 v4 兼容表面policy与私有_runtime参数、EvaluationResult兼容类型、to_v4_check_result等全部移除不要试图保留governance.yaml运行时文件夹解析已被移除任何governance.yaml/governance.yml文件在棘轮扫描中都会被计数属于必须清除的对象策略组合使用原生extends不要再依赖迁移器或运行时合成策略层次AgentMesh Wire Protocol 策略引擎不受影响它使用独立的 AgentMesh 规则 schema不属于本次迁移范围验证途径ratchet 门在每次 Pull Request 运行.github/workflows/v4-removal-ratchet.yml单元测试见 test_check_v4_ratchet.py基线见 v4_ratchet_baseline.json迁移工具的差分与迁移测试可参考agent-governance-python/agt-policies/tests/下的测试用例。七、结语v4 策略语言移除是 AGT 走向单一策略契约的关键一步它用一个 AST 级、跨语言、对文档与 YAML/JSON 数据全覆盖的严格棘轮把「消灭 v4」变成可度量的工程约束又用「迁移工具 差分测试 允许清单」为存量 v4 用户提供了唯一受支持的出口。整个演进以内部绞杀推进、以原子化发布收尾最终把运行时收敛到 ACS 清单这一唯一事实来源。对 v4 用户而言理解字段处置表、尽早盘点并执行单向迁移是平滑过渡到 v5 世界的前提。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考