
Agent Governance Toolkit 的 Microsoft.Agents 扩展验证指南在 .NET 中为 AI Agent 接入治理中间件【免费下载链接】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/maf-integration/06-dotnet-extension-validation验证示例展开讲解如何通过共享的AgentGovernance.Extensions.Microsoft.Agents扩展包把 AGT 策略执行能力以中间件形式挂接到真实的Microsoft.Agents.AIMAFAgent 管线中。读完本文你将掌握两种接入方式WithGovernance(...)钩子方式与显式AgentFrameworkGovernanceAdapter中间件方式、最小策略文件的编写、阻断行为的判定逻辑以及该扩展包在源码层面的实现原理。为什么需要这个验证示例MAFMicrosoft Agent Framework生态下的其他示例如examples/maf-integration/01-loan-processing/dotnet、examples/maf-integration/05-devops-deploy/dotnet各自携带了场景专属的治理代码。06-dotnet-extension-validation的存在意义在于用最小化的可运行应用证明共享扩展包在没有场景脚手架的情况下也能独立工作。该示例是一个repo 内验证样例repo-local validation sample而非可随意复制的独立 Demo项目文件通过ProjectReference直接引用仓库内的agent-governance-dotnet项目见 MicrosoftAgentsExtensionValidation.csproj从而保证验证的是当前分支上精确的适配器代码。具体验证三类能力钩子方式hook option通过agent.WithGovernance(...)为现有AIAgent附加治理治理中间件方式governance middleware option通过AgentFrameworkGovernanceAdapter显式构造可复用的中间件桥阻断行为基于同一份共享扩展包验证被阻断的 run 请求与被阻断的 tool 调用。示例文件构成该验证样例由三个文件组成位于 examples/maf-integration/06-dotnet-extension-validation/dotnet文件作用Program.cs可运行的验证应用串联三种演示流程policies/maf_validation.yaml最小化的 allow/deny 策略规则MicrosoftAgentsExtensionValidation.csproj本地项目文件引用仓库内 AGT 项目其中MicrosoftAgentsExtensionValidation.csproj的关键点在于ItemGroup ProjectReference Include..\..\..\..\agent-governance-dotnet\src\AgentGovernance\AgentGovernance.csproj / ProjectReference Include..\..\..\..\agent-governance-dotnet\src\AgentGovernance.Extensions.Microsoft.Agents\AgentGovernance.Extensions.Microsoft.Agents.csproj / PackageReference IncludeMicrosoft.Agents.AI Version1.3.0 / /ItemGroup它同时引用核心包AgentGovernance提供GovernanceKernel与扩展包AgentGovernance.Extensions.Microsoft.Agents提供 MAF 适配器目标框架为net8.0并且通过CopyToOutputDirectory将策略文件policies/maf_validation.yaml拷贝到输出目录第 17-21 行。这也解释了Program.cs中为什么用AppContext.BaseDirectory拼接策略路径。两种接入方式钩子与显式中间件示例首先创建一个共享的治理内核Governance Kernel它是对策略引擎、审计与指标的统一封装var policyPath Path.Combine(AppContext.BaseDirectory, policies, maf_validation.yaml); var kernel new GovernanceKernel(new GovernanceOptions { PolicyPaths new() { policyPath }, EnablePromptInjectionDetection true, });随后依次运行三个演示流程钩子方式、显式适配器 Builder 方式、函数中间件回调方式。方式一WithGovernance(...)钩子var innerAgent new DemoAgent(hook-agent); var governedAgent innerAgent.WithGovernance( kernel, new AgentFrameworkGovernanceOptions { DefaultAgentId did:agentmesh:hook-agent, EnableFunctionMiddleware false, }); await ShowRunAsync(governedAgent, summarize approved account activity); await ShowRunAsync(governedAgent, transfer funds);这是扩展包对外暴露的最薄入口。从源码看AgentFrameworkGovernanceExtensions.cs 中AIAgent.WithGovernance(GovernanceKernel, options)扩展方法会先构造AgentFrameworkGovernanceAdapter再调用agent.AsBuilder().WithGovernance(adapter).Build()完成包装——钩子方式本质上是显式中间件方式的语法糖。方式二显式AgentFrameworkGovernanceAdapter Buildervar innerAgent new DemoAgent(builder-agent); var adapter new AgentFrameworkGovernanceAdapter( kernel, new AgentFrameworkGovernanceOptions { DefaultAgentId did:agentmesh:builder-agent, EnableFunctionMiddleware false, }); var governedAgent innerAgent .AsBuilder() .WithGovernance(adapter) .Build();显式构造适配器的价值在于可复用同一份AgentFrameworkGovernanceAdapter可以挂到任意 MAF agent 或 builder 上而不必复制翻译代码。AgentFrameworkGovernanceExtensions.cs 中的AIAgentBuilder.WithGovernance(adapter)会调用builder.Use(runFunc: adapter.RunAsync, runStreamingFunc: adapter.RunStreamingAsync)注册 run 中间件当EnableFunctionMiddleware为 true 时再追加builder.Use(adapter.InvokeFunctionAsync)注册函数调用中间件。方式三函数中间件回调形状var adapter new AgentFrameworkGovernanceAdapter( kernel, new AgentFrameworkGovernanceOptions { DefaultAgentId did:agentmesh:tool-agent, EnableFunctionMiddleware true, }); await ShowFunctionAsync(adapter, lookup_rate, 4.5% apr); await ShowFunctionAsync(adapter, deploy_prod, deployment started);ShowFunctionAsync构造了一个真实的FunctionInvocationContext通过AIFunctionFactory.Create创建模拟函数并通过Arguments传入environment参数然后调用adapter.InvokeFunctionAsync(...)。注意这里刻意以最小化的方式演示中间件回调的真实形状——完整FunctionInvokingChatClient管线不在该最小验证应用的范围内这也是原 README 明确声明的边界。策略文件最小化的 allow/deny 规则验证示例的策略文件 policies/maf_validation.yaml 是 AGT 策略语言的最小可运行样例apiVersion: governance.toolkit/v1 version: 1.0 name: maf-validation-policy default_action: allow rules: - name: block-transfers condition: message transfer funds action: deny priority: 100 - name: block-prod-deploy condition: tool_name deploy_prod action: deny priority: 100策略语义非常直观default_action: allow默认放行未命中任何规则时允许执行规则block-transfers当 run 请求的消息文本恰为transfer funds时拒绝对应Program.cs中的第二个 run 请求规则block-prod-deploy当工具名为deploy_prod时拒绝对应函数演示中的生产部署工具priority: 100规则优先级用于多条规则命中时的裁决顺序。其中message与tool_name两个条件变量的来源正是适配器在 AgentFrameworkGovernanceAdapter.cs 中构造的评估上下文run 级评估时适配器把[message] inputText、[agent_name]、[message_count]、[has_session]组装进字典第 60-66 行再交给Kernel.PolicyEngine.Evaluate(agentId, context)工具级评估时Kernel.EvaluateToolCall(agentId, context.Function.Name, ResolveToolArguments(context))会把函数名作为tool_name参与条件匹配第 153-157 行。运行方式与预期输出在仓库检出目录下运行确保ProjectReference的相对路径能正确解析cd examples/maf-integration/06-dotnet-extension-validation/dotnet dotnet run必须从该仓库检出运行因为项目文件通过相对路径..\..\..\..\agent-governance-dotnet\...引用仓库内的 AGT 源码项目。预期输出应包含四类结果allowed run放行的 run 请求穿过被包装的 MAF agent例如summarize approved account activityblocked run被拒绝的 run 请求返回Blocked by governance policy: ...例如transfer fundsallowed tool放行的工具调用返回模拟的工具结果例如lookup_rate返回4.5% aprblocked tool被拒绝的工具调用返回Blocked by governance policy: ...例如deploy_prod。ShowRunAsync的判断逻辑以响应文本是否包含Blocked by governance policy来区分BLOCKED与ALLOWEDShowFunctionAsync则以context.Terminate标记判定阻断Program.cs 第 122-125 行。源码级原理适配器如何实现治理run 级治理RunAsync/RunStreamingAsyncAgentFrameworkGovernanceAdapter.cs 中的RunAsync是 run 级治理的核心调用链解析标识与上下文通过ResolveAgentId、ResolveAgentName、ResolveInputText、ResolveSessionId把 MAF 的AIAgent、AgentSession、ChatMessage翻译成 AGT 可识别的输入策略评估Kernel.PolicyEngine.Evaluate(agentId, context)得到PolicyDecision审计与指标当Kernel.AuditEnabled时Kernel.AuditEmitter.Emit(...)依据决策结果发射PolicyCheck或PolicyViolation事件Kernel.Metrics?.RecordDecision(...)记录决策耗时与是否限流放行/阻断decision.Allowed为 false 时返回BlockedRunResponseFactory或默认的Blocked by governance policy: {decision.Reason}响应否则透传给内层innerAgent.RunAsync(...)。RunStreamingAsync第 89-138 行与之一致只是把阻断响应转换成AgentResponseUpdate流后yield break。工具级治理InvokeFunctionAsyncInvokeFunctionAsync 是函数中间件回调的核心调用Kernel.EvaluateToolCall(agentId, context.Function.Name, ResolveToolArguments(context))评估工具调用被拒绝时设置context.Terminate true终止调用链返回BlockedToolResultFactory或默认的Blocked by governance policy: {decision.Reason}字符串放行时调用next(context, cancellationToken)继续内层工具执行。ResolveToolArguments对参数做了归一化若FunctionInvocationContext.Arguments是字典则逐个拷贝否则以arguments键包裹保证策略条件中的变量名稳定可预测。身份解析策略适配器采用三级回退的 agent DID 解析ResolveAgentId优先使用Options.AgentIdResolver?.Invoke(agent, session)的自定义解析器其次基于 agent 的Name属性生成did:agentmesh:{slugified-name}最后回退到Options.DefaultAgentId默认值did:agentmesh:unknown-agent。配置项速查AgentFrameworkGovernanceOptionsAgentFrameworkGovernanceOptions.cs 定义了扩展包的完整配置面属性默认值说明EnableFunctionMiddlewaretrue是否在 run 中间件之外附加函数调用中间件DefaultAgentIddid:agentmesh:unknown-agent无法推断 agent 标识时的回退 DIDAgentIdResolvernull从 MAF agent 与会话解析 agent DID 的自定义委托InputTextResolvernull提取 run 级评估消息文本的委托默认取最后一条非空用户消息ToolArgumentsResolvernull将函数参数转换为策略条件字典的委托BlockedRunResponseFactorynull自定义被阻断 run 的用户可见响应BlockedToolResultFactorynull自定义被阻断工具调用的返回结果两个关键约束值得注意EnableFunctionMiddleware true仅对支持函数调用中间件的 MAF agent 有效例如基于FunctionInvokingChatClient兼容栈的 agent。如果只需要消息/run 级治理应显式设置为false让适配器只走 run 中间件路径——这正是示例中前两个演示流程的做法扩展包不会替你创建 MAF agent它假定你已有一个真实的Microsoft.Agents.AIAIAgent或AIAgentBuilder然后在它周围挂接治理中间件详见扩展包的 README.md。与其他 MAF 集成场景的关系06-dotnet-extension-validation是examples/maf-integration六个场景中的最后一个专门验证共享 .NET 扩展包maf-integration 场景总览。前五个场景贷款处理、客户服务、医疗、IT 工单、DevOps 部署各自携带场景专属治理代码与策略文件而本场景证明了一旦扩展包验证通过MAF 应用可以在多个场景之间共享同一个治理钩子无需复制任何 MAF→AGT 的翻译代码。对于生产 MAF 应用可直接通过 NuGet 安装扩展包dotnet add package Microsoft.AgentGovernance与dotnet add package Microsoft.AgentGovernance.Extensions.Microsoft.Agents而不必像本验证样例那样使用ProjectReference指向仓库内源码。完整安装方式与两种集成选项可参考扩展包的 README.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),仅供参考