Agent Governance Toolkit 实时治理演示实战：策略拦截、工具沙箱、异常检测与 Merkle 审计全栈指南

Agent Governance Toolkit 实时治理演示实战策略拦截、工具沙箱、异常检测与 Merkle 审计全栈指南【免费下载链接】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仓库中的examples/demos演示体系讲解如何在真实 LLM 后端OpenAI / Azure OpenAI或本地 Ollama之上用完整治理中间件栈实现实时治理强制每一次 API 调用、每一个策略决策、每一条审计记录都是真实发生的而非模拟数据。读完本文你将掌握 RuntimeGovernanceMiddleware、CapabilityGuardMiddleware、RogueDetectionMiddleware 三层中间件的协作原理学会用 YAML Rego 声明策略、跑通 loan-processing 示例、理解 Merkle 链审计与治理仪表盘的接入方式并能快速定位仓库中对应的源码与测试文件深入验证。演示要回答的问题什么是“实时治理”大多数 Agent 安全演示停留在“纸上谈兵”策略文件写好了但从未真正经过一次 LLM 调用。而本仓库的examples/demos/README.md明确声明其核心定位——Demonstrates real-time governance enforcement using real LLM calls即演示中的每次调用、每条策略判定、每个审计条目都是真实链路产物。该演示覆盖四类典型治理场景对应四层可独立组合的中间件场景治理层效果1. 策略强制Policy EnforcementRuntimeGovernanceMiddlewareYAML 策略放行普通搜索提示词但在LLM 被调用之前拦截**/internal/**等受限内容2. 能力沙箱Capability SandboxingCapabilityGuardMiddlewareLLM 请求工具调用时治理层放行run_code拒绝write_file3. 异常检测Rogue DetectionRogueDetectionMiddleware行为异常引擎检测到 50 次调用突发burst自动隔离quarantine该 Agent4. 内容过滤Content FilteringRuntimeGovernanceMiddleware多组提示词批量评估危险内容被阻断、安全内容被转发审计链路Audit TrailAuditLog Merkle 链每一条决策都被密码学哈希链接可校验、防篡改架构总览治理层插在 LLM 之前演示的架构可以概括为一张垂直切片图Agent 内部自顶向下依次经过三层中间件随后才到达真实 LLM API------------------------------------------------------- | Agent (with real OpenAI / Azure OpenAI backend) | | -------------------------------------------------- | | | RuntimeGovernanceMiddleware (YAML policy eval) | -- Blocks before LLM | | CapabilityGuardMiddleware (tool allow/deny) | -- Intercepts tools | | RogueDetectionMiddleware (anomaly scoring) | -- Behavioral SRE | -------------------------------------------------- | | | | | Real LLM API Call (gpt-4o-mini) | ------------------------------------------------------- | | v v AuditLog (Merkle) RogueAgentDetector agentmesh.governance agent_sre.anomaly这个架构的关键设计点在于阻断发生在调用 LLM 之前Blocks before LLM与工具调用被中途拦截Intercepts tools。策略判定失败时中间件直接抛出MiddlewareTerminationLLM 根本不会收到危险提示词工具被拒时函数调用在抵达执行器之前就被终止。从源码结构看这正是 maf_adapter.py 中四类中间件的职责划分RuntimeGovernanceMiddleware继承AgentMiddleware处理整个 agent 调用CapabilityGuardMiddleware与RogueDetectionMiddleware继承FunctionMiddleware处理单次函数调用。前置条件两种运行模式标准模式安装两个 Python 包pip install -e agent-governance-python/agt-policies pip install -e agent-governance-python/agent-os第一个包提供策略执行所需的 Rego / 策略引擎支撑对应agt-policies目录第二个包提供 Agent OS 运行时与治理中间件实现agent_os.integrations.maf_adapter即位于其中。无 API Key 模式对接本地 Ollama 开源模型演示同样支持在本地 OpenAI 兼容服务器上运行无需付费 Key 或任何密钥。OpenAI 客户端会自动读取OPENAI_BASE_URL环境变量因此指向 Ollama 只需两个环境变量。这也是 CI 使用的模式——CI 会用 Meta Llama 3.1 实测整个治理栈ollama serve ollama pull llama3.1 export OPENAI_BASE_URLhttp://127.0.0.1:11434/v1 export OPENAI_API_KEYollama # 占位符Ollama 会忽略它 python examples/maf-integration/01-loan-processing/python/main.py --model llama3.1要点说明OPENAI_API_KEY传任意占位值即可Ollama 不校验--model llama3.1指定本地模型这条命令实际运行的是 loan-processing 示例入口说明该示例同时支持真实 LLM 与本地模型两种后端。运行演示Contoso Bank 贷款处理示例python examples/maf-integration/01-loan-processing/python/main.py该入口位于 main.py代码非常精简完整演示了“加载清单 → 创建上下文 → 输入评估”三步from agent_control_specification import AgentControl from agent_os.integrations.maf_adapter import MAFKernel root Path(__file__).resolve().parent runtime AgentControl.from_manifest(root / policies / manifest.yaml) kernel MAFKernel(runtimeruntime) context kernel.create_context(loan-example) for prompt in (Review the current request, SSN 123-45-6789): result kernel.input(context, prompt) print(prompt, result.verdict)AgentControl.from_manifest(...)从策略清单文件构建治理运行时MAFKernelMicrosoft Agent Framework 适配内核是 AGT 5.0 的 v5 入口源码中标注为AGT 5.0 v5 entrypointkernel.input(ctx, prompt)触发 AGT 的input干预点评估返回AdapterResult其verdict字段给出判定结论。仓库自带的 sample_output.md 给出了预期输出Review the current request allow SSN 123-45-6789 deny“Review the current request”被放行而包含社会安全号码SSN的SSN 123-45-6789被拒绝——这正是场景 4“内容过滤”的最小可复现版本。策略配置深度解析Manifest Regoloan 示例的策略配置由两部分组成位于examples/maf-integration/01-loan-processing/python/policies/目录下。manifest.yaml声明策略与干预点manifest.yaml 使用agent_control_specification格式版本0.4.0-alpha.1声明治理清单agent_control_specification_version: 0.4.0-alpha.1 metadata: name: loan-governance version: 1.0 extends: [] policies: loan_safety: type: rego bundle: . query: data.agt.examples.maf.loan.result intervention_points: input: policy_target: $.input.body policy: id: loan_safety pre_tool_call: policy_target: $.tool_call.args policy: id: loan_safety逐项解读policies.loan_safety声明一条名为loan_safety的 Rego 策略bundle: .指向当前目录query指定查询入口data.agt.examples.maf.loan.resultintervention_points.input在input输入干预点对$.input.body应用loan_safety策略——即每次用户输入进入 Agent 前先做策略评估intervention_points.pre_tool_call在pre_tool_call工具调用前干预点对$.tool_call.args应用同一条策略——即 LLM 请求调用工具时参数也要过一遍策略。同一个策略复用在两个干预点体现了“input 管提示词、pre_tool_call 管工具参数”的双重防线设计。loan.regoRego 规则本体loan.rego 定义了实际判定逻辑package agt.examples.maf.loan import rego.v1 blocked if regex.match((?i)(\b\d{3}-\d{2}-\d{4}\b|social security|tax records?), sprintf(%v, [input.policy_target.value])) result : {decision: deny, reason: loan_safety} if blocked result : {decision: allow, reason: safe} if not blocked关键点正则(?i)(\b\d{3}-\d{2}-\d{4}\b|social security|tax records?)同时匹配SSN 格式如123-45-6789、关键词social security与tax record(s)并忽略大小写命中即返回{decision: deny, reason: loan_safety}否则返回{decision: allow, reason: safe}input.policy_target.value指向干预点配置的policy_targetinput 时为$.input.bodypre_tool_call 时为$.tool_call.args因此同一条规则可以同时过滤提示词与工具参数。源码级纵深四个可组合的治理中间件演示所依赖的治理中间件全部实现在 maf_adapter.py 中。其模块文档声明“Each middleware works independently and can be composed in any combination”每个中间件独立工作可以任意组合。这意味着你可以按需只启用策略层、或策略层 审计层、或全量四层。RuntimeGovernanceMiddleware输入级策略强制继承自 MAF 的AgentMiddleware在process()中提取最后一条用户消息调用kernel.evaluate_input()走 AGTinput干预点。从源码看其处理逻辑包含三个分支DENYbridge_result.allowed为假时构造“⛔ Policy violation: {reason}”的用户可见响应写入审计event_typepolicy_violationpolicy_decisiondeny并抛出MiddlewareTermination——LLM 不会被调用TRANSFORM重写当策略引擎返回 transform 判定时中间件尝试把脱敏后的文本写回消息对象若无法写入例如消息对象只读同样视为阻断并记录审计REFUSE分支保证“无法脱敏即拒绝”的 fail-closed 语义ALLOW记录policy_evaluation审计后放行call_next()。这一实现细节说明内容过滤不仅是“拦与放”还支持就地改写如脱敏后继续处理且改写失败会回退为拒绝杜绝绕过。CapabilityGuardMiddleware工具级能力沙箱继承自 MAF 的FunctionMiddleware在每次函数调用前执行kernel.evaluate_pre_tool_call()。源码关键行为从FunctionInvocationContext提取工具名与参数组装成 args dict若bridge_result.allowed为假或结果不适用于 dict 类型参数则记录tool_blocked审计并以“⛔ Tool ... is not permitted by governance policy”终止调用若策略返回 transform则把脱敏后的参数写回context.arguments让下游看到的是治理层净化后的载荷调用结束后记录tool_invocation的start/complete两条审计完成一次工具的完整生命周期追踪。演示场景 2 中“放行run_code、拒绝write_file”正是由这一层实现工具名不满足策略即被拦截与输入无关。RogueDetectionMiddleware行为级 SRE 异常检测同样是FunctionMiddleware但职责从“单次调用是否合规”上升到“Agent 整体行为是否异常”。源码实现每次工具调用先detector.record_action(...)把观测喂给检测器调用detector.assess(agent_id)得到综合风险评估quarantine_recommended为真记录rogue_detection/quarantine审计并抛出MiddlewareTerminationAgent 被直接隔离风险等级为 MEDIUM / HIGH 但未达隔离线记录 warning 审计后放行执行。检测器本体位于 rogue_detector.py其模块文档明确对标OWASP ASI-10Agent 失控检测综合三类信号工具调用频率尖峰ToolCallFrequencyAnalyzer、动作熵偏离ActionEntropyScorer、能力画像违规CapabilityProfileDeviation合并为单一风险评分并给出自动隔离建议。其RogueDetectorConfig提供可调阈值参数默认值含义frequency_window_seconds60.0频率统计窗口秒frequency_z_threshold2.5频率 Z-score 阈值超过即异常frequency_min_windows5频率分析最少窗口数entropy_low_threshold/entropy_high_threshold0.3 / 3.5动作熵正常区间entropy_min_actions10熵分析最少动作数capability_violation_weight1.0能力画像违规权重quarantine_risk_levelHIGH触发隔离的最低风险等级演示场景 3 的“50 次调用突发被自动隔离”就是由频率分析器在默认窗口下捕捉到的尖峰触发的。组合工厂create_governance_middlewaremaf_adapter.py末尾提供组合工厂一条调用即可组装完整治理栈from agent_os.integrations.maf_adapter import create_governance_middleware middleware create_governance_middleware( runtimeruntime, # AgentControl.from_manifest(...) 的产物 agent_iddefault-agent, enable_rogue_detectionTrue, # 默认开启依赖 agent-sre audit_logNone, # 缺省时自动创建 agentmesh AuditLog ) agent Agent(nameresearcher, instructionsYou are a research assistant., middlewaremiddleware)从源码看该工厂的组装顺序为AuditTrailMiddleware若存在审计日志→RuntimeGovernanceMiddleware→CapabilityGuardMiddleware→ 可选RogueDetectionMiddlewareenable_rogue_detectionTrue且安装了 agent-sre 时追加。AuditTrailMiddleware在每次 Agent 调用前后各写一条审计并把起始条目 ID 写入context.metadata[audit_entry_id]供下游关联——这就是演示“Audit Trail”一行的完整链路。Merkle 链审计每条决策都可校验演示架构图中的审计组件来自agentmesh.governance包实现在 audit.py。其模块文档将其定位为Append-only JSON log with Merkle tree integrity verification追加式 JSON 日志 Merkle 树完整性校验条目通过AuditLog或MerkleAuditChain添加时自动进行哈希链接。从源码看AuditEntry是 pydantic 模型包含entry_id默认audit_ 16 位十六进制 UUIDtimestamp/issued_at/completed_at决策时间与完成时间分离第三方校验者可据此计算动作延迟、区分“决定时间”与“结果时间”哈希字段由链式结构在写入时自动填充后续条目引用前一条的哈希形成不可篡改的链。结合中间件实现可以看到具体的事件类型约定policy_violation、policy_evaluation、tool_blocked、tool_invocation、rogue_detection、agent_invocation——即无论输入拦截、工具拒绝还是异常隔离都会在同一个审计链上留下可验证记录。治理仪表盘单屏透视 Agent 舰队演示还附带一个参考性Streamlit 治理仪表盘位于 examples/demos/governance-dashboard/用于对 Agent 舰队提供单屏总览舰队总览、影子 Agent 检测、生命周期监控、策略评估流、Agent 间信任热力图。cd examples/demos/governance-dashboard pip install -r requirements.txt streamlit run app.py # 或docker-compose up启动后浏览器打开http://localhost:8501。五个页面分别对应页面展示内容Fleet OverviewKPI 卡片、按类型 / 状态 / 风险 / 负责人分布、完整 Agent 表格Shadow Agents无身份 Agent、风险构成、处置建议注册 AgentMesh、指派负责人、应用策略Lifecycle Monitor供给漏斗、凭据状态、孤儿候选、事件时间线Policy Feedallow / deny / escalate 指标、动作构成、Top 被拒动作Trust HeatmapAgent 间信任评分矩阵与信任层级分布需要强调的边界该仪表盘默认使用模拟演示数据demo_data.py 中的合成生成器如generate_fleet/generate_policy_events/generate_trust_matrix/generate_lifecycle_events目的是无需部署 AGT 基础设施即可探索概念。若要接入真实 AgentMesh EventBus的实时数据可参考 agent-governance-python/agent-mesh/examples/06-trust-score-dashboard/若想基于真实数据自建前端则使用agent-governance-python/agent-mesh/src/agentmesh/dashboard/的 DashboardAPI 后端。这也再次印证本文的“实时治理演示”与“演示仪表盘”是两套不同的东西前者跑真实 LLM 与真实策略后者默认展示模拟数据。关键文件速查文件用途examples/maf-integration/原生 ACS MAF 场景loan-processing 即位于其 01-loan-processing 子目录examples/demos/governance-dashboard/实时 Streamlit 治理仪表盘默认模拟数据agent-governance-python/agent-os/src/agent_os/integrations/maf_adapter.py治理中间件RuntimeGovernance / CapabilityGuard / AuditTrail / RogueDetectionagent-governance-python/agent-mesh/src/agentmesh/governance/audit.pyMerkle 链审计日志agent-governance-python/agent-sre/src/agent_sre/anomaly/rogue_detector.pyRogue Agent 检测器OWASP ASI-10examples/maf-integration/01-loan-processing/python/policies/manifest.yaml策略清单与干预点声明examples/maf-integration/01-loan-processing/python/policies/loan.regoRego 判定规则SSN / 敏感词过滤examples/maf-integration/01-loan-processing/python/main.py可复现的 loan 示例入口小结与验证路径本文从examples/demos/README.md出发还原了一条完整的实时治理链路真实 LLM 调用gpt-4o-mini 或本地 Llama 3.1之前由三层中间件完成输入策略评估、工具能力沙箱与行为异常检测所有决策统一落入 Merkle 链审计日志并可通过 Streamlit 仪表盘观察舰队全貌。你可以按以下路径自行验证每一层按“前置条件”安装两个包直接运行 main.py对照 sample_output.md 确认allow/deny输出修改 loan.rego 的正则观察判定变化理解 Rego 策略与policy_target的对应关系阅读 maf_adapter.py 中四个中间件与create_governance_middleware工厂理解组合顺序与MiddlewareTermination的阻断语义阅读 audit.py 与 rogue_detector.py核对审计事件类型与检测阈值配置启动 governance-dashboard 体验舰队可视化并留意其模拟数据边界。【免费下载链接】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），仅供参考