Agent Governance Toolkit policy-engine 代码库实战指南agent-control-spec 重定向后的目录结构、三裁决运行时契约与构建测试【免费下载链接】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导读本文以 policy-engine/AGENTS.md 为骨架系统梳理 Agent Governance ToolkitAGT策略层 policy-engine 的仓库结构、ACSAgent Control Specification术语体系、三裁决运行时不变式、各语言 SDK 的构建与测试命令以及参与该模块开发时必须遵守的变更规则。读完本文你将掌握如何在该仓库中定位策略引擎、宿主 SDK、规范与测试资产理解allow / deny / transform三裁决模型的由来与翻译规则并能够按官方命令跑通 Rust、Node、.NET、Python 各条构建与测试链路。背景策略运行时已重定向到 agent-control-specAGT 的策略决策运行时不再在本仓库内 vendored。它从 registry 以agent-control-spec发布并基于 agent-hooks 控制契约AGENT-HOOKS-0.1重新落地。policy-engine/这一目录承载的是 AGT 叠加在该运行时之上的全部资产core/是一个为期一个发布周期的弃用 shimdeprecation shim用于保持历史agent_control_specification_core符号可导入同时补充上游 crate 未携带的表面artifact 校验、受限 manifest YAML 解析器、更丰富的遥测 sink、策略输入摘要。sdk/rust/是AGT 的宿主 SDK承担 AGENT-HOOKS-0.1 第 8 至 10 节规定的宿主义务。在修改本目录任何内容之前务必先阅读 policy-engine/docs/acs-retarget.md。该文档完整记录了这次重定向的来龙去脉pinned 版本为agent-control-spec 0.4.0-alpha.3、agent-hooks-sdk 0.1.0-alpha.52026-09-08 验证manifest 语法版本保持0.4.0-alpha.1以及 verdict 由五值改为三值等全部破坏性变更。代码库布局AGENTS.md 给出了 policy-engine 的顶层布局每一块的职责如下结合仓库实际内容核对路径用途core/覆盖agent-control-spec的弃用 shim并补充上游 crate 未携带的表面artifact 校验、受限 manifest YAML 解析器、更丰富的遥测 sink、策略输入摘要。实际源码见 core/src其中 core/src/artifact_validation.rs、core/src/manifest_yaml.rs、core/src/telemetry_sinks.rs、core/src/identity.rs 分别对应这四块表面JSON Schema 位于 core/schema。sdk/rust/AGT 的宿主 SDK。承担 AGENT-HOOKS-0.1 第 8 至 10 节的宿主义务transform 应用、evaluate_only、approval 解析、identity 计算。宿主义务实现在 sdk/rust/src/hostC ABI 在 sdk/rust/src/ffi.rs。sdk/python/重定向后的 PyO3 绑定覆盖 AGT 的 Rust 宿主 SDK保留旧版 Python 宿主 API。sdk/node/重定向后的 napi 绑定覆盖 AGT 的 Rust 宿主 SDK保留旧版 Node 宿主 API。sdk/dotnet/基于原生 core 的 .NET SDK外加 framework adapter 形状与测试。integrations/参考 annotator、OpenTelemetry 集成 crate、Rig 集成 crate。generator/ACS 策略 artifact 生成器acs-generateCLI。spec/规范性规范与 JSON Schema入口为 spec/SPECIFICATION.md 与 spec/schemamanifest、approval、cedar_advice 及 wire 层 schema另有 AGT 扩展规范 spec/agt。docs/设计说明、安全模型、部署说明、runbook 与 SDK 表面指南。examples/可运行的 ACS 宿主示例与生成的 demo agent。tests/一致性 fixtures、形式化模型、性能 harness 与符合性资产其中跨 SDK 一致性 fixtures 在 tests/parity形式化模型在 tests/formal。注意布局表与 policy-engine/README.md 中的 Layout 表是互补关系README 从运行时的角度描述各目录角色policy/lib/为内置 Rego/Cedar 库、sdk/另含 Go 绑定AGENTS.md 则从贡献者视角强调core/的 shim 身份与sdk/rust/的宿主义务归属。词汇表统一使用 ACS 术语AGENTS.md 明确要求在写 issue、文档、测试和代码注释时使用 ACS 术语不要引入 predecessor 项目旧 AGT 引擎已移除的概念也不要重新引入五裁决模型。核心术语如下术语含义Interception pointagent-hooks 的叫法InterventionPoint是 AGT 已退休的拼写。对应重定向映射InterventionPoint→agent_hooks::InterceptionPoint、InterventionPointRequest→runtime::EvaluationRequest、InterventionPointResult→runtime::EvaluationResult。Snapshot宿主为某次评估组装的一个完整 JSON 文档是运行时读取的关于 agent 及其环境的唯一输入spec/SPECIFICATION.md §1.2。Policy input运行时构建的规范化策略输入对象恰好包含五个成员intervention_point、policy_target、snapshot、annotations、tool§7。Verdictallow、deny、transform三值闭合集合AGENT-HOOKS-0.1 §5.1。Transform唯一会改变值的决策且被限定作用于 policy targeteffects plane 已移除。Annotator产生 annotation 的 dispatcher输出被隔离写入annotations.name。Manifest 与extends路径根为$target不再是$policy_target文件型extends解析被限定在顶层 manifest 根目录内。Fail closed runtime error引擎发出runtime_error:*host_error:*命名空间保留给宿主interceptor 绝不能发出它。Host approval handling宿主对可提升 denyliftabledeny的审批处理。三裁决模型warn 与 escalate 的去向AGENTS.md 强调裁决集合闭合为三且明确翻译规则旧值新值warnallow携带warnings[]Verdict::warn仅是构造器糖escalate可提升的deny携带approval块该规则在规范性层面由 spec/SPECIFICATION.md §13.1 支撑warn归一化为allow并向warnings[]追加一条escalate归一化为携带approval块的deny将动作延迟到宿主的审批路径§17.1。同时原因命名空间被拆分引擎发出runtime_error:*保留命名空间策略输出不得使用此前缀。host_error:*保留给宿主。AGT 宿主 SDK 作为宿主会在以下场景合成host_error:*approval resolver 失败、approval identity 不匹配、approval 未解析、流式拒绝——这些名字来自 agent-hooks 的保留集合。运行时不变式stateless、deterministic、fail closedAGENTS.md 列出的运行时不变式与 spec/SPECIFICATION.md §1.1 的 invariants 一一对应运行时无状态。宿主必须为每一次评估提供完整 snapshot运行时不得保留任何会影响后续 verdict 的可变状态。单次调用内、随调用栈传递的状态是允许的进程级或模块级 registry 则不允许。运行时错误 fail closed 为deny并使用保留的runtime_error:*reason且任何以运行时错误结束的路径都不得应用 transform。transform是唯一改变值的决策且限定作用于 policy target——引擎绝不会改动 snapshot、annotations、投影的 tool 或宿主状态§14。应用 transform、尊重evaluate_only、解析 approval、计算 identity 都是宿主义务AGENT-HOOKS-0.1 第 8 至 10 节它们位于 sdk/rust/src/host绝不允许被推回策略平面。Annotator 输出隔离在annotations.name下不得覆盖或遮蔽snapshot、policy_target、tool、intervention_point等根成员§10。文件型extends解析限定在顶层 manifest 根合并是增量的冲突定义、引用环、缺失文件、URL 获取失败都必须 fail closed§2.2。Approval identity 必须绑定到被审批动作的 canonical policy input。关于第 7 点可以在源码层面看到具体实现。宿主 SDK 的 sdk/rust/src/host/evaluation.rs 中HostEvaluation携带input_identity与enforced_identity两个 SHA-256 摘要input_identity是策略实际评估的 canonical policy input 的摘要enforced_identity是应用 transform 路径后的 canonical policy input 的摘要对非 transform 决策及 evaluate-only 模式等于input_identity。审批路径绑定enforced_identity从而保证审批人同意的是将要真正执行的动作spec/SPECIFICATION.md §13.1。宿主义务的载体在 sdk/rust/src/host/approval.rsApprovalResolver回调与ApprovalOutcome::{Allow, Deny, Suspend}与 sdk/rust/src/host/evaluation.rsfrom_engine/from_engine_with_limits完成 transform 应用与重新校验。值得注意的是transform 应用后宿主必须重建完整有效 snapshot并校验其字节与深度限制from_engine_with_limits这一检查在 enforce 与 evaluate-only 两种模式下都会执行——只校验替换后的 target 会遗漏环境状态从而可能放行超限动作。该共享 helper 同时服务 Rust、Python、Node 与 .NET C ABI。构建与测试按区域执行命令AGENTS.md 给出的构建测试策略是先跑你所改动区域的窄命令再在行为跨 SDK 时跑更宽的命令合并前必须通过。区域命令Rust workspacecargo fmt --all -- --check、cargo clippy --workspace --all-targets -- -D warnings、cargo test --workspaceCore examplecargo run -p agent_control_specification --example basic_host --quietGeneratorpython -m pip install ./generator pytest然后pytest generatorNode SDKcd sdk/node npm ci npm test.NET SDKcd sdk/dotnet dotnet build AgentControlSpecification.sln然后dotnet run --project tests/AgentControlSpecification.TestsFormal modelQuint 可用时quint test tests/formal/acs_mediation.qntRego policiescd policy/lib opa test .两点运行前提需要格外注意OPA 依赖OPA 支持的测试与示例需要opa在PATH上。本地验证 CI parity 时设置AGENT_CONTROL_REQUIRE_OPA1让 OPA 支撑的测试大声失败而不是被跳过policy-engine/QUICKSTART.md Step 9 也强调了这一点。工作区范围该 Cargo workspace 嵌入 AGT 顶层 workspace因此在policy-engine/内执行 scoped workspace 命令从仓库根也可以使用包级命令例如cargo build -p agt_core_engine、cargo test -p agt_core_enginepolicy-engine/README.md Build 一节。构建与测试的底层验证资产除了命令本身AGENTS.md 与相关文档还揭示了几类验证资产供你在修改后自我检查跨 SDK parity fixturestests/parity 下存放verdict_dispatch_canonical.json、error_mapping_canonical.json、resource_limits_canonical.json、telemetry_redaction_canonical.json、artifact-validation-cases.json、drift-catalog.json等一致性资产断言 Rust、Python、Node、.NET 四个 SDK 对同一批 snapshot 给出相同结果。跨 SDK 契约变化时必须同步更新这些 fixtures。回归测试sdk/rust/tests 包含fail_closed_error_parity.rs、upstream_compatibility.rs、conformance_corpus.rs、streaming_conformance.rs、agent_loop_exercise.rs、artifact_validation.rs覆盖 fail closed 错误 parity、与 pinned 上游版本的兼容性、一致性语料与流式一致性。安全回归案例manifest_from_url的 SSRF 防护在 policy-engine/docs/acs-retarget.md 有完整说明测试覆盖127.1、2130706433、0x7f000001、0177.0.0.1、127.0.0TAB.1等非常规字面量并绑定 loopback listener 断言不会产生连接。变更规则决策语义归上游SDK 只做宿主编排AGENTS.md 对修改 policy-engine 的贡献者提出了明确的规则这些规则直接映射到重定向后的架构边界保持变更聚焦避免无关清理。纯决策行为属于上游agent-control-spec不要 fork 语义进core/。应在上游仓库提 proposal而不是在本仓库内复制一份决策逻辑。这一点在 policy-engine/docs/acs-retarget.md 中反复强调例如恢复远程 bundle 或远程 prompt 来源属于上游提案本仓库选择 fail closedreject_removed_manifest_fields遍历每个 policy 定义、annotator 声明与每个 interception point 的绑定返回runtime_error:manifest_invalid并指名位置与字段。SDK 代码负责宿主异步编排与惯用 adapter 形状宿主义务停留在 sdk/rust/src/host绝不推回策略平面。跨 SDK 契约变化时更新 parity fixturestests/parity。仅当规范性契约变化时才更新规范文本spec/SPECIFICATION.md。绝不提交 secrets、凭据或敏感载荷原文到日志或 fixtures 中——这与 docs/security-model.md 中telemetry 默认内容脱敏、事件不携带 policy target、tool 参数、model 输出、annotation 载荷、transform 值、secret 与个人数据的约定一致。与安全模型的呼应policy-engine 的安全姿态在 docs/security-model.md 中有完整定义ACS 是无状态、确定性的 intervention point 策略运行时只计算可移植的策略决策与变换宿主负责执行。信任边界位于input、pre_model_call、post_model_call、pre_tool_call、post_tool_call、output等介入点manifest 与 Rego bundle 是受信任策略未受插桩的调用路径不在 ACS 保证范围内。AGENTS.md 中fail closed runtime error与approval identity 绑定 canonical policy input两条不变式正是该安全模型在实现层的落点。散文风格约定最后AGENTS.md 对文档散文有一组明确的风格约束参与贡献时应遵守文档散文必须密实且技术化不要使用 em dash—散文句子中不要使用冒号——冒号仅允许出现在标题、表格、代码块、YAML 与 JSON 中。这与该仓库文档一贯的紧凑风格一致例如 spec/SPECIFICATION.md 全文即以此风格撰写。小结与下一步围绕 policy-engine/AGENTS.md本文梳理了 policy-engine 在 agent-control-spec 重定向后的完整图景目录布局中core/是 shim、sdk/rust/是宿主义务载体词汇表中三裁决模型allow / deny / transform取代了五裁决模型运行时不变式确立了 stateless、deterministic、fail closed 三大属性与宿主义务边界构建测试命令覆盖 Rust、Node、.NET、Python、Generator、形式化模型与 Rego 七条链路。如果你要继续深入推荐按以下顺序阅读仓库资料运行时语义的权威契约policy-engine/spec/SPECIFICATION.md重定向全过程与安全缺口记录policy-engine/docs/acs-retarget.md宿主集成逐步指南policy-engine/QUICKSTART.md威胁与安全模型policy-engine/docs/security-model.mdSDK 表面选型policy-engine/docs/sdk-surfaces.md【免费下载链接】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），仅供参考