Agent Governance Toolkit 实战用 MAFKernel 与原生 ACS Runtime 构建 IT Helpdesk 输入治理【免费下载链接】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本篇技术指南以仓库内 examples/maf-integration/04-it-helpdesk/python 示例为骨架讲解如何将 Agent Governance Toolkit 的治理能力原生接入 Microsoft Agent FrameworkMAF。示例通过MAFKernel挂载原生 ACSAgent Control Specification运行时在不依赖任何 LLM 凭据的前提下对「安全请求」与「危险请求」给出确定性判定并演示如何用kernel.as_runtime_middleware()把治理中间件接入完整 MAF Agent 应用。读完本文你将掌握原生 ACS 运行时的加载方式、输入干预点的 Rego 策略编写、以及 MAF 中间件组合的底层原理。示例背景为什么需要一个无需 LLM 的治理演示IT Helpdesk 场景的核心风险是帮助台 Agent 被授权执行系统类操作时可能被诱导或误触发破坏性命令如递归删除、关闭安全机制、导出凭据。此类风险需要在 Agent 真正执行动作之前被拦截且拦截判定必须快速、确定、可复现——因此示例刻意选择不依赖 LLM 凭据的纯策略引擎判定路径治理判定由原生 ACS 运行时 Rego 策略完成结果确定且可单元化验证演示脚本可离线运行适合作为 CI 冒烟测试或文档级示例相同的策略与干预点配置可无缝升级为真实 MAF Agent 的运行时中间件。该示例属于 examples/maf-integration/README.md 中 6 个 MAF 集成场景的第 4 个场景矩阵将其定位为「Destructive shell requests」破坏性 Shell 请求的治理演示与之并列的场景还包括贷款处理敏感身份数据、客服提示注入、医疗病历标识符、DevOps 部署破坏性部署请求等。快速运行两行命令跑通治理判定原文档给出的运行方式极为精简按以下步骤即可复现cd examples/maf-integration/04-it-helpdesk/python pip install -r requirements.txt python main.pyrequirements.txt 固定了示例所需的依赖版本agent-framework1.5.0 agent-os-kernel3.2.2 agentmesh-platform3.2.2 agent-sre3.2.2其中agent-framework提供 MAF 运行时类型BaseChatClient、ChatMiddlewareLayer等agent-os-kernel提供本示例核心的MAFKernel位于 agent-governance-python/agent-os/src/agent_os/integrations/maf_adapter.pyagentmesh-platform与agent-sre则为可选的审计日志与异常行为检测提供依赖支撑。运行后的输出是确定性的见 sample_output.mdReview the current request allow Run rm -rf /tmp/data deny两条请求分别得到allow与deny证明同一套策略对安全输入放行、对破坏性输入拦截。代码走读main.py 的完整调用链main.py 是示例的全部逻辑完整代码及其作用拆解如下from pathlib import Path from agent_control_specification import AgentControl from agent_os.integrations.maf_adapter import MAFKernel def main() - None: root Path(__file__).resolve().parent runtime AgentControl.from_manifest( root / policies / manifest.yaml ) try: kernel MAFKernel(runtimeruntime) context kernel.create_context(helpdesk-example) for prompt in (Review the current request, Run rm -rf /tmp/data): result kernel.input(context, prompt) print(prompt, result.verdict) finally: runtime.close()调用链可分四步理解加载原生 ACS 运行时AgentControl.from_manifest(...)读取policies/manifest.yaml把声明式的治理配置策略绑定、干预点、策略目标编译为运行时对象AgentControl构造 MAF 适配内核MAFKernel(runtimeruntime)将原生运行时桥接进 MAF 生态其底层通过get_adapter_runtime(runtime)获得AdapterRuntime桥见 maf_adapter.py创建执行上下文kernel.create_context(helpdesk-example)以会话名helpdesk-example建立一次治理评估的上下文AdapterExecutionState携带agent_id与session_id逐条评估输入kernel.input(context, prompt)走 AGT 的input干预点返回包含verdictallow/deny的结果对象并打印。try/finally中的runtime.close()确保运行时资源被正确释放——这是示例代码中容易被忽略但值得在生产中沿用的资源管理习惯。治理清单解析manifest.yaml 的干预点绑定manifest.yaml 是治理配置的核心完整内容如下agent_control_specification_version: 0.4.0-alpha.1 metadata: name: helpdesk-governance version: 1.0 extends: [] policies: helpdesk_safety: type: rego bundle: . query: data.agt.examples.maf.helpdesk.result intervention_points: input: policy_target: $.input.body policy: id: helpdesk_safety pre_tool_call: policy_target: $.tool_call.args policy: id: helpdesk_safety各字段的实战含义如下配置项取值作用agent_control_specification_version0.4.0-alpha.1声明 ACS 清单协议版本运行时据此校验语法与特性兼容性metadata.name/metadata.versionhelpdesk-governance/1.0治理包的标识与版本便于审计与追溯extends[]继承的基类清单列表示例为空表示完全独立定义policies.helpdesk_safety.typerego策略引擎类型为 RegoOPA 规则语言policies.helpdesk_safety.bundle.Rego 策略包目录.表示与 manifest 同目录policies.helpdesk_safety.querydata.agt.examples.maf.helpdesk.resultRego 查询入口返回带decision与reason的结果对象intervention_points.input.policy_target$.input.body输入干预点把用户消息正文作为策略评估目标intervention_points.pre_tool_call.policy_target$.tool_call.args工具调用前干预点把工具参数作为策略评估目标关键设计是同一策略helpdesk_safety被同时绑定到两个干预点input用户输入到达 Agent 时与pre_tool_call工具即将被调用时。这意味着即使破坏性命令在输入阶段绕过了第一道检查例如被工具参数拼装也会在工具执行前被第二道检查拦截——这是纵深防御在干预点层面的体现。策略逻辑helpdesk.rego 如何判定破坏性请求helpdesk.rego 定义了全部判定规则package agt.examples.maf.helpdesk import rego.v1 blocked if regex.match((?i)(rm\s-rf|disable\ssecurity|dump\scredentials), sprintf(%v, [input.policy_target.value])) result : {decision: deny, reason: helpdesk_safety} if blocked result : {decision: allow, reason: safe} if not blocked逐行解读包与版本package agt.examples.maf.helpdesk声明策略包路径与 manifest 中query: data.agt.examples.maf.helpdesk.result的data.前缀一一对应import rego.v1采用 Rego v1 语法语义命中条件blocked规则用不区分大小写的正则(?i)(rm\s-rf|disable\ssecurity|dump\scredentials)匹配input.policy_target.value——即 manifest 指定的干预点目标值。三种破坏性模式分别为递归删除命令、关闭安全机制、导出凭据决策输出result根据blocked的真假产出denyreason 为helpdesk_safety或allowreason 为safe这正是main.py中result.verdict的数据来源。可以验证Review the current request不匹配任何模式 →allowRun rm -rf /tmp/data命中rm\s-rf→deny。若需要扩充规则只需在同目录的 Rego 文件中追加模式如shutdown|reboot、format\s\w:等或增加额外的result分支。底层原理MAFKernel 与四类可组合治理中间件MAFKernel并非一个黑盒而是 Agent Governance Toolkit 为 MAF 提供的原生治理适配器。从 maf_adapter.py 的源码结构看它围绕原生 ACS 运行时封装了四个可独立组合的中间件RuntimeGovernanceMiddlewareAgentMiddleware在每次 Agent 调用前把最后一条用户消息经 AGTinput干预点评估拒绝时写入可见的⛔ Policy violation响应并抛出MiddlewareTermination允许时还可应用策略返回的 transform 改写消息正文见源码 maf_adapter.pyCapabilityGuardMiddlewareFunctionMiddleware在每次 MAF 函数调用前把工具名与参数经 AGTpre_tool_call干预点评估阻止未被治理策略允许的工具见 maf_adapter.pyAuditTrailMiddlewareAgentMiddleware为每次 Agent 调用记录执行前/后的防篡改审计条目并把审计条目 ID 写入context.metadata[audit_entry_id]供下游关联见 maf_adapter.pyRogueDetectionMiddlewareFunctionMiddleware把每次工具调用喂给agent_sre.anomaly.RogueAgentDetector高危 Agent 被隔离终止、中危调用记录警告后放行见 maf_adapter.py。MAFKernel的wrap()/unwrap()为空操作因为治理能力是通过中间件列表注入 MAF Agent 的而不是代理包裹整个 Agent见 maf_adapter.py。as_runtime_middleware()与as_capability_guard()分别返回前两类中间件见 maf_adapter.py而create_governance_middleware()则是把审计、运行时治理、能力守卫、异常检测组合成完整治理栈的便捷工厂函数见 maf_adapter.py。升级到真实 Agentkernel.as_runtime_middleware()原文档指出在完整的 MAF 应用中通过kernel.as_runtime_middleware()将治理中间件挂到 Agent Runtime 上且职责划分明确Runtime 侧Agent Governance Toolkit拥有决策decision、变换transform与审批approval能力MAF 中间件侧拥有框架生命周期与审计上下文。将示例升级为真实 Agent 的最小接入方式源自 maf_adapter.py 的用法注释与 examples/maf-integration/README.md 的说明from agent_framework import Agent from agent_os.integrations.maf_adapter import create_governance_middleware middleware create_governance_middleware( policy_directorypolicies/, # 或直接传入已加载的 runtime allowed_tools[web_search, file_read], enable_rogue_detectionTrue, ) agent Agent( nameresearcher, instructionsYou are a research assistant., middlewaremiddleware, )治理栈一旦挂载Agent 的每一次输入与每一次工具调用都会经过策略评估拒绝行为以用户可见的⛔消息呈现同时写入审计日志——这与示例脚本中kernel.input(context, prompt)得到的verdict是同一套评估引擎在不同接入形态下的两种表现。同场景 .NET 对照完整的 IT Helpdesk 治理演示若需要对比 Python 与 .NET 两种接入方式同目录下提供了 04-it-helpdesk/dotnet 的完整版本。其 README 说明它使用真实的 MAF Agent 与原生Microsoft.Agents.AI中间件演示四大能力策略执行提权与凭据类提示在 Agent 运行前即被拒绝能力沙箱受治理的 MAF 工具允许安全 Helpdesk 操作、阻止管理员或凭据库访问异常 Agent 检测重复的管理命令尝试触发异常评分与隔离审计追踪治理事件镜像进 Merkle 链式合规日志。运行方式同样是确定性的、无需真实 LLM 凭据cd examples/maf-integration/04-it-helpdesk/dotnet dotnet run小结与延伸通过这个 30 行不到的 Python 示例可以完整看到 Agent Governance Toolkit 的 MAF 集成链路manifest.yaml声明治理配置 →AgentControl.from_manifest加载原生 ACS 运行时 →MAFKernel桥接进 MAF 生态 → Rego 策略在input与pre_tool_call两个干预点做出确定性判定。无需 LLM 凭据的特性让它可以无缝嵌入 CI 管道做策略回归而as_runtime_middleware()又让同一套策略能直接升级为生产 Agent 的运行时治理。进一步探索仓库可参考其余 5 个 MAF 集成场景examples/maf-integration/README.md同系列其他场景的 Python 版策略清单如 01-loan-processing、02-customer-service可用于对比不同风险主题的 Rego 写法MAF 适配器完整源码agent-governance-python/agent-os/src/agent_os/integrations/maf_adapter.pyMAF 集成相关文档与架构说明docs/integrations 与 docs/architecture如适用。【免费下载链接】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），仅供参考 Agent Governance Toolkit 实战：用 MAFKernel 与原生 ACS Runtime 构建 IT Helpdesk 输入治理
Agent Governance Toolkit 实战用 MAFKernel 与原生 ACS Runtime 构建 IT Helpdesk 输入治理【免费下载链接】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本篇技术指南以仓库内 examples/maf-integration/04-it-helpdesk/python 示例为骨架讲解如何将 Agent Governance Toolkit 的治理能力原生接入 Microsoft Agent FrameworkMAF。示例通过MAFKernel挂载原生 ACSAgent Control Specification运行时在不依赖任何 LLM 凭据的前提下对「安全请求」与「危险请求」给出确定性判定并演示如何用kernel.as_runtime_middleware()把治理中间件接入完整 MAF Agent 应用。读完本文你将掌握原生 ACS 运行时的加载方式、输入干预点的 Rego 策略编写、以及 MAF 中间件组合的底层原理。示例背景为什么需要一个无需 LLM 的治理演示IT Helpdesk 场景的核心风险是帮助台 Agent 被授权执行系统类操作时可能被诱导或误触发破坏性命令如递归删除、关闭安全机制、导出凭据。此类风险需要在 Agent 真正执行动作之前被拦截且拦截判定必须快速、确定、可复现——因此示例刻意选择不依赖 LLM 凭据的纯策略引擎判定路径治理判定由原生 ACS 运行时 Rego 策略完成结果确定且可单元化验证演示脚本可离线运行适合作为 CI 冒烟测试或文档级示例相同的策略与干预点配置可无缝升级为真实 MAF Agent 的运行时中间件。该示例属于 examples/maf-integration/README.md 中 6 个 MAF 集成场景的第 4 个场景矩阵将其定位为「Destructive shell requests」破坏性 Shell 请求的治理演示与之并列的场景还包括贷款处理敏感身份数据、客服提示注入、医疗病历标识符、DevOps 部署破坏性部署请求等。快速运行两行命令跑通治理判定原文档给出的运行方式极为精简按以下步骤即可复现cd examples/maf-integration/04-it-helpdesk/python pip install -r requirements.txt python main.pyrequirements.txt 固定了示例所需的依赖版本agent-framework1.5.0 agent-os-kernel3.2.2 agentmesh-platform3.2.2 agent-sre3.2.2其中agent-framework提供 MAF 运行时类型BaseChatClient、ChatMiddlewareLayer等agent-os-kernel提供本示例核心的MAFKernel位于 agent-governance-python/agent-os/src/agent_os/integrations/maf_adapter.pyagentmesh-platform与agent-sre则为可选的审计日志与异常行为检测提供依赖支撑。运行后的输出是确定性的见 sample_output.mdReview the current request allow Run rm -rf /tmp/data deny两条请求分别得到allow与deny证明同一套策略对安全输入放行、对破坏性输入拦截。代码走读main.py 的完整调用链main.py 是示例的全部逻辑完整代码及其作用拆解如下from pathlib import Path from agent_control_specification import AgentControl from agent_os.integrations.maf_adapter import MAFKernel def main() - None: root Path(__file__).resolve().parent runtime AgentControl.from_manifest( root / policies / manifest.yaml ) try: kernel MAFKernel(runtimeruntime) context kernel.create_context(helpdesk-example) for prompt in (Review the current request, Run rm -rf /tmp/data): result kernel.input(context, prompt) print(prompt, result.verdict) finally: runtime.close()调用链可分四步理解加载原生 ACS 运行时AgentControl.from_manifest(...)读取policies/manifest.yaml把声明式的治理配置策略绑定、干预点、策略目标编译为运行时对象AgentControl构造 MAF 适配内核MAFKernel(runtimeruntime)将原生运行时桥接进 MAF 生态其底层通过get_adapter_runtime(runtime)获得AdapterRuntime桥见 maf_adapter.py创建执行上下文kernel.create_context(helpdesk-example)以会话名helpdesk-example建立一次治理评估的上下文AdapterExecutionState携带agent_id与session_id逐条评估输入kernel.input(context, prompt)走 AGT 的input干预点返回包含verdictallow/deny的结果对象并打印。try/finally中的runtime.close()确保运行时资源被正确释放——这是示例代码中容易被忽略但值得在生产中沿用的资源管理习惯。治理清单解析manifest.yaml 的干预点绑定manifest.yaml 是治理配置的核心完整内容如下agent_control_specification_version: 0.4.0-alpha.1 metadata: name: helpdesk-governance version: 1.0 extends: [] policies: helpdesk_safety: type: rego bundle: . query: data.agt.examples.maf.helpdesk.result intervention_points: input: policy_target: $.input.body policy: id: helpdesk_safety pre_tool_call: policy_target: $.tool_call.args policy: id: helpdesk_safety各字段的实战含义如下配置项取值作用agent_control_specification_version0.4.0-alpha.1声明 ACS 清单协议版本运行时据此校验语法与特性兼容性metadata.name/metadata.versionhelpdesk-governance/1.0治理包的标识与版本便于审计与追溯extends[]继承的基类清单列表示例为空表示完全独立定义policies.helpdesk_safety.typerego策略引擎类型为 RegoOPA 规则语言policies.helpdesk_safety.bundle.Rego 策略包目录.表示与 manifest 同目录policies.helpdesk_safety.querydata.agt.examples.maf.helpdesk.resultRego 查询入口返回带decision与reason的结果对象intervention_points.input.policy_target$.input.body输入干预点把用户消息正文作为策略评估目标intervention_points.pre_tool_call.policy_target$.tool_call.args工具调用前干预点把工具参数作为策略评估目标关键设计是同一策略helpdesk_safety被同时绑定到两个干预点input用户输入到达 Agent 时与pre_tool_call工具即将被调用时。这意味着即使破坏性命令在输入阶段绕过了第一道检查例如被工具参数拼装也会在工具执行前被第二道检查拦截——这是纵深防御在干预点层面的体现。策略逻辑helpdesk.rego 如何判定破坏性请求helpdesk.rego 定义了全部判定规则package agt.examples.maf.helpdesk import rego.v1 blocked if regex.match((?i)(rm\s-rf|disable\ssecurity|dump\scredentials), sprintf(%v, [input.policy_target.value])) result : {decision: deny, reason: helpdesk_safety} if blocked result : {decision: allow, reason: safe} if not blocked逐行解读包与版本package agt.examples.maf.helpdesk声明策略包路径与 manifest 中query: data.agt.examples.maf.helpdesk.result的data.前缀一一对应import rego.v1采用 Rego v1 语法语义命中条件blocked规则用不区分大小写的正则(?i)(rm\s-rf|disable\ssecurity|dump\scredentials)匹配input.policy_target.value——即 manifest 指定的干预点目标值。三种破坏性模式分别为递归删除命令、关闭安全机制、导出凭据决策输出result根据blocked的真假产出denyreason 为helpdesk_safety或allowreason 为safe这正是main.py中result.verdict的数据来源。可以验证Review the current request不匹配任何模式 →allowRun rm -rf /tmp/data命中rm\s-rf→deny。若需要扩充规则只需在同目录的 Rego 文件中追加模式如shutdown|reboot、format\s\w:等或增加额外的result分支。底层原理MAFKernel 与四类可组合治理中间件MAFKernel并非一个黑盒而是 Agent Governance Toolkit 为 MAF 提供的原生治理适配器。从 maf_adapter.py 的源码结构看它围绕原生 ACS 运行时封装了四个可独立组合的中间件RuntimeGovernanceMiddlewareAgentMiddleware在每次 Agent 调用前把最后一条用户消息经 AGTinput干预点评估拒绝时写入可见的⛔ Policy violation响应并抛出MiddlewareTermination允许时还可应用策略返回的 transform 改写消息正文见源码 maf_adapter.pyCapabilityGuardMiddlewareFunctionMiddleware在每次 MAF 函数调用前把工具名与参数经 AGTpre_tool_call干预点评估阻止未被治理策略允许的工具见 maf_adapter.pyAuditTrailMiddlewareAgentMiddleware为每次 Agent 调用记录执行前/后的防篡改审计条目并把审计条目 ID 写入context.metadata[audit_entry_id]供下游关联见 maf_adapter.pyRogueDetectionMiddlewareFunctionMiddleware把每次工具调用喂给agent_sre.anomaly.RogueAgentDetector高危 Agent 被隔离终止、中危调用记录警告后放行见 maf_adapter.py。MAFKernel的wrap()/unwrap()为空操作因为治理能力是通过中间件列表注入 MAF Agent 的而不是代理包裹整个 Agent见 maf_adapter.py。as_runtime_middleware()与as_capability_guard()分别返回前两类中间件见 maf_adapter.py而create_governance_middleware()则是把审计、运行时治理、能力守卫、异常检测组合成完整治理栈的便捷工厂函数见 maf_adapter.py。升级到真实 Agentkernel.as_runtime_middleware()原文档指出在完整的 MAF 应用中通过kernel.as_runtime_middleware()将治理中间件挂到 Agent Runtime 上且职责划分明确Runtime 侧Agent Governance Toolkit拥有决策decision、变换transform与审批approval能力MAF 中间件侧拥有框架生命周期与审计上下文。将示例升级为真实 Agent 的最小接入方式源自 maf_adapter.py 的用法注释与 examples/maf-integration/README.md 的说明from agent_framework import Agent from agent_os.integrations.maf_adapter import create_governance_middleware middleware create_governance_middleware( policy_directorypolicies/, # 或直接传入已加载的 runtime allowed_tools[web_search, file_read], enable_rogue_detectionTrue, ) agent Agent( nameresearcher, instructionsYou are a research assistant., middlewaremiddleware, )治理栈一旦挂载Agent 的每一次输入与每一次工具调用都会经过策略评估拒绝行为以用户可见的⛔消息呈现同时写入审计日志——这与示例脚本中kernel.input(context, prompt)得到的verdict是同一套评估引擎在不同接入形态下的两种表现。同场景 .NET 对照完整的 IT Helpdesk 治理演示若需要对比 Python 与 .NET 两种接入方式同目录下提供了 04-it-helpdesk/dotnet 的完整版本。其 README 说明它使用真实的 MAF Agent 与原生Microsoft.Agents.AI中间件演示四大能力策略执行提权与凭据类提示在 Agent 运行前即被拒绝能力沙箱受治理的 MAF 工具允许安全 Helpdesk 操作、阻止管理员或凭据库访问异常 Agent 检测重复的管理命令尝试触发异常评分与隔离审计追踪治理事件镜像进 Merkle 链式合规日志。运行方式同样是确定性的、无需真实 LLM 凭据cd examples/maf-integration/04-it-helpdesk/dotnet dotnet run小结与延伸通过这个 30 行不到的 Python 示例可以完整看到 Agent Governance Toolkit 的 MAF 集成链路manifest.yaml声明治理配置 →AgentControl.from_manifest加载原生 ACS 运行时 →MAFKernel桥接进 MAF 生态 → Rego 策略在input与pre_tool_call两个干预点做出确定性判定。无需 LLM 凭据的特性让它可以无缝嵌入 CI 管道做策略回归而as_runtime_middleware()又让同一套策略能直接升级为生产 Agent 的运行时治理。进一步探索仓库可参考其余 5 个 MAF 集成场景examples/maf-integration/README.md同系列其他场景的 Python 版策略清单如 01-loan-processing、02-customer-service可用于对比不同风险主题的 Rego 写法MAF 适配器完整源码agent-governance-python/agent-os/src/agent_os/integrations/maf_adapter.pyMAF 集成相关文档与架构说明docs/integrations 与 docs/architecture如适用。【免费下载链接】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），仅供参考