Microsoft Agent Framework - 对 Agent 进AOP（Middleware）编程

目录

代码基础：创建带工具的 Agent

切面 1：Run Middleware（对整次 Run 执行做前后拦截）

对应输出场景（Run Middleware 日志）

切面 2：Function Calling Middleware（拦截工具调用过程）

对应输出场景（Function Calling Middleware 日志）

可扩展示例：增加计时切面

常见可插入的切面思路

总结

上一篇

在构建 AI Agent 时，经常需要为“执行对话”和“工具调用”加入横切能力（Cross-Cutting Concerns），例如：

• 日志与审计

• 性能与计时

• 异常捕获与统一包装

• 调试与可观测性

• 安全与访问控制

在 Microsoft Agent Framework（Microsoft.Extensions.AI/Microsoft.Agents.AI）中，可以通过“函数式 Middleware”直接对 Agent 运行生命周期进行切面化增强，无需定义类或接口，实现极简、模块化、可组合的拦截。

本文示例展示两类切面：

1. Run Middleware（拦截整个对话执行）

2. Function Calling Middleware（拦截工具调用）

代码基础：创建带工具的 Agent

using Azure.AI.OpenAI; using Microsoft.Agents.AI; using Microsoft.Extensions.AI; using OpenAI; using System.ClientModel; using System.ComponentModel; // 配置（生产环境请用安全方式管理密钥） var azureAiEndpoint = "https://{your-endpoint}.openai.azure.com"; var apiKey = "{YOUR-API-KEY}"; // 1. 定义工具（函数即工具） [Description("Get user information by a given user name.")] static string GetUserInfo([Description("The user name")] string userName) => $"{userName} is from Suzhou, male, 28 years old"; // 2. 创建 Agent 并注册工具 AIAgent agent = new AzureOpenAIClient( new Uri(azureAiEndpoint), new ApiKeyCredential(apiKey)) .GetChatClient("gpt-4o-mini") .CreateAIAgent( instructions: "You are a helpful assistant", tools: [AIFunctionFactory.Create(GetUserInfo)]);

这里通过AIFunctionFactory.Create将一个普通 C# 方法暴露为可被模型自主调用的工具（Function Calling）。

切面 1：Run Middleware（对整次 Run 执行做前后拦截）

作用：记录每次请求输入与模型产生的输出消息。

// 自定义 Run Middleware async Task<AgentRunResponse> CustomAgentRunMiddleware( IEnumerable<ChatMessage> messages, AgentThread? thread, AgentRunOptions? options, AIAgent innerAgent, CancellationToken cancellationToken) { foreach (var chatMessage in messages) { Console.WriteLine($"Input: {chatMessage}"); } var response = await innerAgent .RunAsync(messages, thread, options, cancellationToken) .ConfigureAwait(false); foreach (var chatMessage in response.Messages) { Console.WriteLine($"Output: {chatMessage.Contents[0].ToString()}"); } return response; } // 注册 Run Middleware var agentWithRunMiddleware = agent.AsBuilder() .Use(runFunc: CustomAgentRunMiddleware, runStreamingFunc: null) .Build(); Console.WriteLine(await agentWithRunMiddleware.RunAsync("Show me the information of Jim ?"));

对应输出场景（Run Middleware 日志）

Input: Show me the information of Jim ? Output: Microsoft.Extensions.AI.FunctionCallContent Output: Microsoft.Extensions.AI.FunctionResultContent Output: Jim is a 28-year-old male from Suzhou. Jim is a 28-year-old male from Suzhou.

说明：

• 第一行：原始用户输入

• 中间的 FunctionCall / FunctionResult：模型决定调用工具并返回结果的中间内容

• 最后一行：最终自然语言回答

切面 2：Function Calling Middleware（拦截工具调用过程）

作用：对每次工具调用做审计 / 计时 / 参数检查 / 结果加工等。

// 自定义 Function Calling Middleware async ValueTask<object?> CustomFunctionCallingMiddleware( AIAgent agent, FunctionInvocationContext context, Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next, CancellationToken cancellationToken) { Console.WriteLine($"Function Name: {context.Function.Name}"); var result = await next(context, cancellationToken); Console.WriteLine($"Function Call Result: {result}"); return result; } // 注册 Function Calling Middleware var agentWithFunctionCallingMiddleware = agent.AsBuilder() .Use(CustomFunctionCallingMiddleware) .Build(); Console.WriteLine(await agentWithFunctionCallingMiddleware.RunAsync("Show me the information of Jim ?"));

对应输出场景（Function Calling Middleware 日志）

Function Name: _Main_g_GetUserInfo_0_1 Function Call Result: Jim is from Suzhou, male, 28 years old Jim is a 28-year-old male from Suzhou.

说明：

• Function Name：模型选择调用的工具函数内部生成的名称（可用于审计 / 白名单校验）

• Function Call Result：该工具函数真实返回值

• 最后一行：模型基于工具结果生成的最终回答

可扩展示例：增加计时切面

你可以继续添加更多函数式 Middleware：

async ValueTask<object?> TimingFunctionMiddleware( AIAgent agent, FunctionInvocationContext context, Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next, CancellationToken ct) { var sw = System.Diagnostics.Stopwatch.StartNew(); var result = await next(context, ct); sw.Stop(); Console.WriteLine($"Function {context.Function.Name} elapsed: {sw.ElapsedMilliseconds} ms"); return result; } var enhancedAgent = agent.AsBuilder() .Use(CustomFunctionCallingMiddleware) .Use(TimingFunctionMiddleware) .Use(runFunc: CustomAgentRunMiddleware, runStreamingFunc: null) .Build();

常见可插入的切面思路

• 参数校验与拒绝危险输入

• 结果缓存（相同参数短期复用）

• 异常捕获统一格式化返回

• OpenTelemetry 观测（埋点发送 Span / Metric）

• 权限控制（基于用户上下文阻断某些工具）

总结

Microsoft Agent Framework 的 Middleware 是以“函数”形态实现的，而不是传统的类 / 接口，这种模式非常接近 JavaScript 生态（如 Express / Koa 的中间件管道）。它充分体现了 C# 在现代版本中的函数式编程能力：一等函数、委托、闭包与组合式构建，使得为 Agent 增加切面逻辑变得简洁、高效、低侵入。

借助这种函数式 Middleware，你可以快速迭代智能体的可观测性、调试性与扩展能力，专注核心价值而非样板结构。

下一篇

引入地址