用 agent-governance-toolkit GitHub Action 将 Agent 治理检查接入 CIgovernance-verify 与 policy-evaluate 实战【免费下载链接】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 Toolkit 仓库中的官方 GitHub Action位于 action/action.yml展开讲解如何以最小配置把 Agent 治理验证、插件清单校验与策略评估固化为 CI 必检门禁。读者读完将掌握 Action 的全部输入/输出参数、四种命令governance-verify、marketplace-verify、policy-evaluate、all的用法、严格版本锁定机制以及其底层在仓库源码中的实际调用链从而在自己的仓库里落地一套可审计、可复现的 Agent 治理流水线。一、这个 Action 解决什么问题Agent Governance Toolkit 提供了策略执行、零信任身份、执行沙箱等能力而 action/README.md 中定义的 GitHub Action 是它的 CI 侧入口在每次提交或 PR 时自动检查代理治理状态把治理做成required check必需检查而不是依赖人工自觉。Action 使用composite方式运行从源码 action/action.yml 可以看到其完整执行流程分四步用actions/setup-python配置 Python 运行时通过pip安装指定版本的agent-governance-toolkit[full]当命令涉及原生 Rego 策略时下载并校验 OPA 二进制执行所选治理命令并把结果写入 GITHUB_OUTPUT。二、快速开始最小配置由于 vNEXT 起toolkit-version变为必填使用前必须把它钉死到某个已发布的精确版本例如3.7.0。README 给出的最小配置如下- uses: microsoft/agent-governance-toolkit/actionv2 with: toolkit-version: 3.7.0从 action/action.yml 的实现看安装步骤会先检查AGT_TOOLKIT_VERSION是否为空、再校验版本号是否符合正则最后执行python -m pip install --quiet --no-cache-dir --disable-pip-version-check agent-governance-toolkit[full]$AGT_TOOLKIT_VERSION即安装的是包含[full]扩展依赖的精确版本。官方建议消费者继续使用自己原有的大版本标签如v3并在新版本发布时同步升级toolkit-version。三、四种命令的实战用法3.1 governance-verifyOWASP ASI 合规检查默认命令不指定command时默认执行治理验证用于确认当前环境对 OWASP Agentic Security InitiativeASI各项控制项的覆盖情况- name: Governance Check uses: microsoft/agent-governance-toolkit/actionv2 with: command: governance-verify output-format: json这条命令底层调用的是python -m agent_compliance.cli.main verify见 action/action.yml。仓库源码 agent-governance-python/agent-compliance/src/agent_compliance/cli/main.py#L63-L81 中的cmd_verify会实例化GovernanceVerifier并依据--json/--badge参数输出 JSON 证明、徽章 Markdown 或人类可读摘要。验证内容定义在 agent-governance-python/agent-compliance/src/agent_compliance/verify.py#L59-L110 的OWASP_ASI_CONTROLS映射表中覆盖 10/10 项 OWASP Agentic Top 10 控制项控制项名称对应组件源码模块ASI-01Prompt Injectionagent_os.prompt_injection.PromptInjectionDetectorASI-02Insecure Tool Useagent_os.integrations.tool_aliases.ToolAliasRegistryASI-03Excessive Agencyagent_os.integrations._native_adapter_runtime.NativeAdapterRuntimeASI-04Unauthorized Escalationagent_os.integrations.escalation.EscalationPolicyASI-05Trust Boundary Violationagentmesh.trust.cards.CardRegistryASI-06Insufficient Loggingagentmesh.governance.audit.AuditChainASI-07Insecure Identityagentmesh.identity.agent_id.AgentIdentityASI-08Policy Bypassagentmesh.governance.conflict_resolution.PolicyConflictResolverASI-09Supply Chain Integrityagent_compliance.integrity.IntegrityVerifierASI-10Behavioral Anomalyagentmesh.governance.compliance.ComplianceEngine每个控制项通过模块可导入 组件存在的方式进行探测见 verify.py 的_check_control且动态导入被限制在ALLOWED_MODULE_PREFIXES白名单内verify.py#L32-L44防止验证逻辑被任意模块路径劫持——这是仓库在安全审计MSRC Case 112362后收紧的安全边界。验证结果会被封装为带 SHA-256 哈希的GovernanceAttestationverify.py#L330-L377任何对通过状态、控制项存在性、证据观测值的篡改都会改变摘要因此 CI 输出的 JSON 可以当作不可抵赖的合规证明。3.2 marketplace-verify插件清单校验对要发布到插件市场的 Agent 插件清单做格式与内容校验- name: Verify Plugin uses: microsoft/agent-governance-toolkit/actionv2 with: command: marketplace-verify manifest-path: plugins/my-plugin/plugin.json底层调用为python -m agent_marketplace.cli_commands verify $MANIFESTaction/action.yml。仓库源码 agent-governance-python/agent-marketplace/src/agent_marketplace/cli_commands.py#L175-L219 中的verify_plugin支持generic、auto、copilot-plugin、claude-plugin多种格式检测若传入目录会优先查找plugin.json再回退到agent-plugin.yaml。注意manifest-path在该命令下是必填的缺失会直接以错误退出。3.3 policy-evaluate原生策略评估含 OPA 运行时该命令用于对原生 ACS manifest 策略进行求值判断给定的上下文快照是否被允许- name: Evaluate Policy uses: microsoft/agent-governance-toolkit/actionv2 with: command: policy-evaluate policy-path: policies/manifest.yaml intervention-point: input context-json: {input: {body: Summarize the report}}当command为policy-evaluate或all时Action 会额外安装被锁定的 OPA 运行时action/action.yml#L92-L103从 Open Policy Agent 官方发布地址下载v0.70.0的opa_linux_amd64_static二进制用固定 SHA-25600d114b9...做完整性校验后才赋予执行权限并通过ACS_OPA_PATH环境变量暴露给策略运行时。这里可以看到仓库对供应链安全的重视即使是对第三方 OPA 二进制的获取也采用固定版本 哈希校验的双重约束。求值过程通过内联 Python 调用agt.policies.AgtRuntime完成action/action.yml#L155-L188将intervention-point干预点与context-json快照传入runtime.evaluate()最终输出包含allowed、verdict、reason_code、message的 JSON 结果并以decision.is_allowed()决定进程退出码。policy-path在该命令下同样必填。3.4 all一键跑完整治理套件需要同时覆盖治理验证、插件校验与策略评估时使用all命令- name: Full Governance Suite uses: microsoft/agent-governance-toolkit/actionv2 with: command: all manifest-path: plugins/my-plugin/plugin.json policy-path: policies/manifest.yaml从 action/action.yml#L190-L233 的实现看all会依次执行治理验证固定以 JSON 输出→ 插件校验仅当提供manifest-path→ 策略评估仅当提供policy-path。任一环节失败都会把整体结果置为失败实现一次运行、全量把关。3.5 插件市场 PR 工作流完整示例README 给出了一个针对插件目录变更的完整 CI 示例可直接复制使用name: Plugin Governance on: pull_request: paths: [plugins/**] jobs: governance: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Verify plugin manifest uses: microsoft/agent-governance-toolkit/actionv2 id: verify with: command: marketplace-verify manifest-path: plugins/${{ github.event.pull_request.title }}/plugin.json - name: Governance compliance uses: microsoft/agent-governance-toolkit/actionv2 with: command: governance-verify output-format: json该工作流只监听plugins/**路径的 PR先校验清单、再做整体治理合规检查两次调用之间可以借助步骤id: verify读取输出做后续门禁判断。四、全部输入参数详解Action 支持以下输入均定义于 action/action.yml#L8-L45与 README 表格一致输入说明必填默认值command要执行的验证governance-verify、marketplace-verify、policy-evaluate、all否governance-verifypolicy-path原生 ACS manifest 的路径否空manifest-path插件清单路径marketplace-verify必填否空intervention-pointpolicy-evaluate使用的 ACS 干预点否pre_tool_callcontext-json传给干预点的 JSON 快照否空output-format输出格式text、json、badge否textfail-on-warning有警告不仅错误即失败否falsepython-version使用的 Python 版本否3.12toolkit-version要安装的工具包精确版本如3.7.0是—几个值得注意的细节output-format的badge选项会输出 Shields.io 徽章 Markdown由 verify.py 中的badge_markdown()生成徽章颜色随 OWASP ASI 覆盖率100% 为brightgreen、≥80% 为yellow、其余为red变化可直接嵌入仓库 README。fail-on-warning用于把警告升级为失败当前实现中治理验证的严格判定由GovernanceAttestation.passed全部控制项通过才算 pass决定见 verify.py#L511。五、输出与退出码5.1 输出变量输出说明statuspass或failcontrols-passed通过的治理控制项数仅governance-verifycontrols-total检查的控制项总数仅governance-verifyviolations策略违规数仅policy-evaluateoutput完整命令输出output-format: json时为 JSON输出通过 action/action.yml#L241-L252 写入GITHUB_OUTPUT当output-format为json时Action 会从 JSON 中解析controls_passed与controls_total供下游步骤引用action/action.yml#L135-L141。5.2 退出码代码含义0全部检查通过1一个或多个检查失败失败时 Action 会输出::error::Governance check failed并退出 1action/action.yml#L257-L259从而让 GitHub 把该步骤标记为红色、阻断合入。六、toolkit-version 的严格版本锁定这是使用本 Action 时最需要理解的安全设计。toolkit-version在安装前会经过正则校验^[0-9]\.[0-9]\.[0-9]((a|b|rc)[0-9])?$从 action/action.yml#L86-L89 可以看到版本不合法时 Action 会直接报错退出确保安装命令pip install agent-governance-toolkit[full]$VERSION永远解析到预期发行版。接受的版本3.7.0、3.7.0a1、3.7.0b2、3.7.0rc1——即正式版与 alpha/beta/rc 预发布版。拒绝的版本及原因示例拒绝原因3.7.0.post1/3.7.0.dev0瞬态 post/dev 制品不应作为 CI 基线3.7.0localPEP 440 本地版本标识符在某些 pip 解析器下可能覆盖注册表解析3.7.*/3.7浮动版本破坏可复现性3.7.0; python_version 3环境标记environment markersURL / VCS 引用绕过版本解析的安装来源这一设计把CI 跑在什么版本的治理引擎上完全钉死任何模糊、浮动或可被利用的版本语法都会被拒绝从源头避免依赖混淆与供应链漂移。七、把治理检查升级为强制门禁的落地建议结合本 Action 的能力与仓库现有实践落地时可以参考以下组合拳精确钉版本toolkit-version始终填写已发布的确切版本升级走显式 PR 流程Action 本身使用大版本标签如v2。三种检查分层核心仓库跑governance-verify默认即可插件仓库/目录加marketplace-verify有原生 Rego/ACS 策略的场景加policy-evaluate。产物化合规证据用output-format: json配合output输出把controls-passed/controls-total汇入 PR 评论或外部看板JSON 证明带有 SHA-256 摘要verify.py#L288-L328可长期归档审计。路径限定触发如示例工作流所示用on.pull_request.paths只对受影响目录触发节省 CI 资源。失败即阻断不要吞掉退出码利用退出码 1 让治理检查成为真正意义上的 required check做到治理不过、合并不行。结语本 Action 的价值在于把 Agent 治理从文档约定变成CI 强制约束一套 YAML、四种命令、严格版本锁定即可获得 OWASP ASI 覆盖验证、插件清单校验与原生策略评估三重保障。其底层实现action/action.yml、agent-compliance 验证器、marketplace 校验器也展示了供应链安全与可审计证明在 CI 自动化中的正确姿势值得作为自建治理管线的参考模板。【免费下载链接】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），仅供参考