microsoft/agent-governance-toolkit · 上手攻略

• 仓库：microsoft/agent-governance-toolkit
• 链接：https://github.com/microsoft/agent-governance-toolkit
• 分类：ai · agent-runtime · governance · compliance
• 作者：spark
• 更新：2026-08-18

1. 这是什么

Agent Governance Toolkit (AGT) 是微软在 2025-2026 年推出的开源 agent runtime governance 工具箱。它不重做 agent 框架，而是在 LangChain / CrewAI / OpenAI Agents / AutoGen / Google ADK 等任意框架外，套一层"policy enforcement + identity + sandboxing + audit + SRE"的护栏层。把"agent 是否允许做某动作、是谁做的、能否事后证明"这三个长期悬而未决的问题，从 prompt 礼貌请求（不可靠）挪到确定性应用代码层（structural enforcement）。

⚠️ README 顶部明确："Public Preview -- production-quality public preview releases. May have breaking changes before GA." —— 不是 GA 状态，版本兼容性可能变。

适合：把 agent 推上线、要满足 OWASP Agentic Top 10 / EU AI Act / 内部安全审计的团队；多 agent 共享一把 API key 想做 incident response 的组织。

不适合：还在 prototype 阶段、还没有 policy / identity / audit 三件套诉求的"先跑起来再说"项目。

2. 解决什么问题

README "The Problem" 段把痛点分成三问：

1. 这个动作允许吗？ —— 有 send_email + query_database 权限的 agent 不该能 drop_table。OAuth scope / IAM 角色只能管"能不能连到服务"，管不了"连上之后做什么"。
2. 是哪个 agent 干的？ —— 多 agent 共享一把 API key 出事后，"是某 agent 干的"等于"啥也没说"。
3. 能不能事后证明？ —— 审计员 / 监管要的不可篡改记录：当时哪个 policy 在生效、agent 请求了什么、为什么被允许 / 拒绝。

AGT 的核心论点是：prompt-level safety（"请遵守规则"）不是 control surface，它是对一个随机系统的礼貌请求。README 引用了 OWASP LLM01:2025 原话："it is unclear if there are fool-proof methods of prevention for prompt injection." 与微软自家 Red Teaming 100 Generative AI Products 的论断："mitigations do not eliminate risk entirely"，"red teaming must be a continuous process"。AGT 选择了不在 prompt 层正面对抗，而是把所有 tool call / message send / delegation 在 deterministic application code 层做拦截。

⚠️ 引用核验：AGT README 引用 Andriushchenko et al. 2025 arXiv 2404.02151 时表述"100% attack success rate on GPT-4o, GPT-3.5, Claude 3, and Llama-3 using adaptive attacks with logprob access and suffix optimization, evaluated against the JailbreakBench benchmark (Chao et al., NeurIPS 2024)"。我已 fetch 2404.02151 摘要：该论文确为 ICLR 2025（不是 NeurIPS 2024），abstract 给出 100% ASR 的模型列表是 Vicuna-13B / Mistral-7B / Phi-3-Mini / Nemotron-4-340B / Llama-2-Chat 系列 / Llama-3-Instruct-8B / Gemma-7B / GPT-3.5 / GPT-4o / R2D2 + Claude 全系——不是 AGT README 写的"GPT-4o, GPT-3.5, Claude 3, and Llama-3"这四款。同时 JailbreakBench 2404.01318 作者列表里包含 Andriushchenko，"evaluated against JailbreakBench" 描述大致成立。这是不准确的细节引用 —— AGT 自己也中招了 lessons W33 红线 #1 的"AI 幻觉嵌入真实 ID"：真实论文 ID + 看似合理但有偏差的细节。本攻略不复制 AGT 原话，只核实引用出处。

3. 快速安装

3.1 Python（推荐完整栈）

# Python ≥ 3.11（README "Prerequisites" 硬要求）
pip install "agent-governance-toolkit[full]"

[full] extra 装 governance 全模块；base wheel 只装 compliance CLI。v4.1.0 起多包已整合，原 agent-os-kernel 单独分发被标记 DeprecationWarning，迁移到 agent-governance-toolkit-core（[full] 已包含）。

3.2 跨语言 SDK

3.3 IDE / CLI 集成

# Claude Code
/plugin marketplace add microsoft/agent-governance-toolkit
/plugin install agt-governance@agent-governance-toolkit

# Copilot CLI
npx @microsoft/agent-governance-copilot-cli install

# OpenCode
npm install @microsoft/agent-governance-opencode

3.4 一键可复制最小代码（README "Govern any tool function in two lines"）

# 安装
pip install "agent-governance-toolkit[full]"

# 验证
python -c "from agentmesh.governance import govern; print('ok')"

# policy.yaml（与代码同级）
# apiVersion: governance.toolkit/v1
# name: production-policy
# default_action: allow
# rules:
#   - name: block-destructive
#     condition: "action.type in ['drop', 'delete', 'truncate']"
#     action: deny
#     description: "Destructive operations require human approval"
#   - name: require-approval-for-send
#     condition: "action.type == 'send_email'"
#     action: require_approval
#     approvers: ["security-team"]

from agentmesh.governance import govern

def my_tool(**kwargs):
    # 你原来的工具实现
    return {'rows': 42}

safe_tool = govern(my_tool, policy="policy.yaml")

# 允许的动作 → 正常返回
safe_tool(action="read", table="users")
# {'table': 'users', 'rows': 42}

# 被 deny 的动作 → 抛 GovernanceDenied
safe_tool(action="drop", table="users")
# GovernanceDenied: Action denied by policy rule 'block-destructive':
#   Destructive operations require human approval

3.5 完整 ACS policy decision（推荐作为新 host 默认）

from agent_control_specification import AgentControl, HostSession

control = AgentControl.from_path("manifest.yaml")
session = HostSession(control, agent_id="researcher", session_id="session-1")

result = session.pre_tool_call(
    tool_name="send_email",
    args={"to": "partner@example.net", "body": "Status update"},
)

if not result.verdict.decision.permits:
    raise PermissionError(result.verdict.reason)

ACS 返回 5 种 normalized verdict：allow / warn / deny / escalate / transform。ACS 不执行 tool，也不留隐藏 session state —— 同一个 policy 契约可被 framework adapter / gateway / 自定义 host 共用。

4. 核心用法

4.1 CLI 操作工具

agt doctor                                         # 安装健康检查
agt verify                                         # OWASP 合规检查
agt verify --evidence ./agt-evidence.json --strict # CI 强校验（弱证据即 fail）
agt red-team scan ./prompts/ --min-grade B         # prompt injection 审计
agt lint-policy policies/                          # 校验 policy YAML

4.2 ACS / govern() 双入口的取舍

• govern()：最小代码路径，给"先加一层 guardrail 看效果"用（current wrapper API）。新 host / adapter / 平台 policy 集成推荐用 ACS。
• AgentControl / HostSession：ACS host 接口，确定性 + stateless + fail-closed。verdict 由 host 强制施加，ACS 本身不执行 tool。

4.3 包家族（README "Packages" 表）

4.4 框架集成（README 明示）

govern() 模式通用：包住 application callable。框架生命周期 hook 用 ACS Python SDK 构 snapshot / 强制 verdict。可选 adapter：LangChain / CrewAI / OpenAI Agents / LangGraph / LlamaIndex / Haystack / PydanticAI / Google ADK。

每个 adapter 都附 example：

• examples/acs-email-tool —— 最小 ACS host（snapshot + transform + deny + host enforcement）
• examples/acs-atr-annotator —— 自定义 threat rule 注解
• examples/openai-agents-governed —— OpenAI Agents SDK policy-gated tool calls + trust tiers
• examples/crewai-governed —— CrewAI 多 agent + role-based policy
• examples/smolagents-governed —— HuggingFace smolagents 轻量 governance
• examples/maf-integration —— Microsoft Agent Framework
• examples/mcp-trust-verified-server —— MCP trust-verified server 实现

4.5 额外能力

• MCP Security Gateway —— tool poisoning 检测、drift monitoring、typosquatting、隐藏指令扫描（Spec）
• Shadow AI Discovery —— 在进程、配置、repo 中找未注册 agent
• Governance Dashboard —— 实时可视化（Demo）
• PromptDefense Evaluator —— 12 向量 prompt injection 审计
• Contributor Reputation —— PR/issue 作者社交工程筛查（GitHub Action）

5. 典型适用场景

• OWASP Agentic Top 10 合规落地 —— README badge "10/10 Covered"（详细映射见 docs/compliance/owasp-agentic-top10-architecture.md）
• EU AI Act / ISO 42001 / 内部 SRE 审计 —— 不可篡改审计 + policy 版本化
• 多 agent 共 API key 的事故溯源 —— 每个沙箱独立身份 + decision record
• MCP server 信任 —— tool poisoning / typosquatting / hidden instruction 扫描
• 强化学习训练里加 governance —— Agent Lightning（违规扣分）
• 批量做 prompt injection 红队 —— agt red-team scan

6. 坑与注意

1. Public Preview —— 顶部 disclaimer 明确"May have breaking changes before GA"。production 部署要盯 CHANGELOG.md。
2. 旧 agent-os-kernel 已 deprecation —— import agent_os 触发 DeprecationWarning；迁移到 agent-governance-toolkit-core 或 [full] extra。看 BREAKING_CHANGES.md。
3. v4 → v5 政策迁移 —— 用 agt-policies 一条命令迁，旧的 agent_os.policies rule model 已经没了。
4. policy 写法只覆盖四种 action 形态 —— action.type in [...] 是 YAML 字符串条件，写错就静默 deny（fail-closed）。复杂条件先在 agt lint-policy 校验。
5. [full] extra 不是空集合 —— 包含 core + CLI + framework adapter 等，依赖较多；最小集成用 base + ACS 即可。
6. 框架适配器是"optional adapters" —— 不是 default。README 在 "Framework Integrations" 明示"Optional adapters cover LangChain, CrewAI, ..."。主线 governance 与框架无关；框架适配是 glue layer，不写 adapter 也能用 ACS host。
7. OWASP 覆盖深度 —— README badge 写 "10/10 Covered"，但 README 没把每条对应到哪些 spec 文档。落地前必须回看 docs/compliance/owasp-agentic-top10-architecture.md 实测。
8. 跨语言一致性 —— README "Language Package Matrix" 明示"Python has the full stack"，其它语言只覆盖"core governance (policy, identity, trust, audit)"。若核心控制流在 Rust / Go host 上，policy DSL 是否完整需查 PACKAGE-FEATURE-MATRIX.md。
9. OWASP Top 10 / LLM01:2025 / JailbreakBench 数字引用偏差 —— 见 §2 ⚠️ 段。不要把 AGT README 的话当成事实复述——它自己有不准确的细节引用。
10. License：README badge MIT。但若启用 ACS Rust core 或 SDK 二进制，license 文件在子目录要逐项 verify。
11. Microsoft AI Red Teaming Agent 引用的"Attack Success Rate"是 ASR 家族 —— README 用了"ASR"缩写但没展开；要落地 ASR 量化前需对齐 definition（GPT-4-as-judge？rule-based？人工？）。

7. 与同类对比

简版取舍：要"政策 + 身份 + 审计 + SRE 一站式 + 跨语言 SDK + OWASP 合规 badge" → AGT；要"NVIDIA 硬件 agent 沙箱 + 网络策略" → NemoClaw；要"先把评估 + tracing 跑起来" → LangSmith；要"极致自定义 + 不依赖任何框架" → 自写。

8. 一句话推荐

如果你的 agent 已经在做真实决策、要满足 OWASP Agentic Top 10 / 内部合规 / 跨语言 SDK 部署，Public Preview 阶段的 AGT 是当前最完整的开源 runtime governance 栈；但落地前先确认自己能否容忍 v4→v5 / API breaking change，并对 README 引用的具体数字 / 会议归属独立核验（AGT 自己在引用 Andriushchenko 论文时也写错过会议名）。

来源与不确定处

• 来源（已 fetch 验证）：
• https://raw.githubusercontent.com/microsoft/agent-governance-toolkit/main/README.md 完整 raw（前 14229 字）
• https://microsoft.github.io/agent-governance-toolkit/ 文档首页
• https://arxiv.org/abs/2404.02151 Andriushchenko et al. 论文摘要（验证会议归属 + 模型列表）
• https://arxiv.org/abs/2404.01318 JailbreakBench 论文摘要（验证作者列表）
• 不确定处 / 已发现的引用偏差：
• AGT README "Andriushchenko et al. ICLR 2025" 被错标为 "NeurIPS 2024"：2404.02151 实际接收会议是 ICLR 2025。不复制此引用。
• AGT README 列出的"100% ASR 模型集合"过窄：2404.02151 abstract 实测 12+ 模型（Vicuna-13B / Mistral-7B / Phi-3-Mini / Nemotron-4-340B / Llama-2-Chat-7B/13B/70B / Llama-3-Instruct-8B / Gemma-7B / GPT-3.5 / GPT-4o / R2D2 / Claude 全系），不是 README 列出的 4 款。
• OWASP Agentic Top 10 逐条对应：README badge 写 "10/10 Covered"，但逐条 mapping 表在本攻略未独立 verify——引用前回看 docs/compliance/owasp-agentic-top10-architecture.md。
• AARM Extended R1-R9 / ATF All 5 Elements badge：来自 aarm.dev 与 agentictrustframework.ai，未在本攻略独立 verify 对应证据文档。
• PyPI 当前版本号：PyPI 页被反爬挡住，未独立 verify 最新 release tag。README 内部提到 v4.1.0 做了"45 packages consolidated"重构，但当前 PyPI 是否已 GA v4.1.0、v5 是否进入 public preview需在 PyPI 实测。
• pip install "agent-governance-toolkit[full]" 是否仍为推荐命令：README 明示推荐；实测前假设它可用。
• agt-policies v4 → v5 迁移命令语法：README 一句话提及"agt-policies provides the one-way v4-to-v5 migration command"，但未给出具体 CLI 范例，引用前看 docs/CHANGELOG.md。
• GovernanceDenied 是否真为抛出异常类型：来自 README 范例，未独立 import verify（仓库处于 Public Preview，类型签名可能变）。
• 框架 adapter 列表：README 列了 8+ 框架，但每个 adapter 的当前适配成熟度（alpha/beta/stable）未在本攻略独立 verify。