当前位置：首页 > news >正文

[MAF的Agent管道详解-07]利用AIAgent中间件构建Agent管道

news 2026/5/26 10:46:54

与采用DelegatingChatClient中间件装饰IChatClient对象并构成IChatClient管道的方式类似，我们可以使用DelegatingAIAgent代表的AIAgent中间件来装饰一个AIAgent对象，并构成一个AIAgent管道。通过在不同的阶段插入不同的AIAgent中间件，我们就可以实现对Agent调用的全方位控制和增强。DelegatingAIAgent中间件链条位于整个AIAgent管道的最前端。

1. DelegatingAIAgent

作为AIAgent中间件的一个DelegatingAIAgent类型定义如下。这是一个派生于AIAgent的抽象类，它的核心成员是一个InnerAgent属性，表示被委托的AIAgent对象。我们可以定义DelegatingAIAgent的派生类，通过重写其属性成员和方法来实现对InnerAgent的功能扩展和增强。通过不断地嵌套多个DelegatingAIAgent，我们就可以构建出一个类似于中间件的管道来对AIAgent进行扩展和增强。

虽然DelegatingAIAgent是一个抽象类，但是它为所有的成员都提供了默认的实现，实现实现的方式都一样：直接调用InnerAgent的对应成员。这样一来，我们在定义具体的DelegatingAIAgent时，就只需要重写我们想要增强的成员，而不需要关心其他成员的实现细节了。如下所示的是属性成员、构造函数以及GetService方法的定义的

publicabstractclassDelegatingAIAgent:AIAgent{protectedAIAgentInnerAgent{get;}protectedoverridestring?IdCore=>InnerAgent.Id;publicoverridestring?Name=>InnerAgent.Name;publicoverridestring?Description=>InnerAgent.Description;protectedDelegatingAIAgent(AIAgentinnerAgent)=>InnerAgent=innerAgent;publicoverrideobject?GetService(TypeserviceType,object?serviceKey=null){if(serviceKey!=null||!serviceType.IsInstanceOfType(this)){returnInnerAgent.GetService(serviceType,serviceKey);}returnthis;}}

AIAgent定义了五个抽象方法，分别是针对AgentSession的创建、序列化和反序列化的CreateSessionCoreAsync、SerializeSessionCoreAsync和DeserializeSessionCoreAsync方法，以及针对Agent阻塞式调用和流式响应的RunCoreAsync和RunCoreStreamingAsync方法。它们在DelegatingAIAgent中的实现方法亦是如此。

publicabstractclassDelegatingAIAgent:AIAgent{protectedoverrideValueTask<AgentSession>CreateSessionCoreAsync(CancellationTokencancellationToken=default)=>InnerAgent.CreateSessionAsync(cancellationToken);protectedoverrideValueTask<JsonElement>SerializeSessionCoreAsync(AgentSessionsession,JsonSerializerOptions?jsonSerializerOptions=null,CancellationTokencancellationToken=default)=>InnerAgent.SerializeSessionAsync(session,jsonSerializerOptions,cancellationToken);protectedoverrideValueTask<AgentSession>DeserializeSessionCoreAsync(JsonElementserializedState,JsonSerializerOptions?jsonSerializerOptions=null,CancellationTokencancellationToken=default)=>InnerAgent.DeserializeSessionAsync(serializedState,jsonSerializerOptions,cancellationToken);protectedoverrideTask<AgentResponse>RunCoreAsync(IEnumerable<ChatMessage>messages,AgentSession?session=null,AgentRunOptions?options=null,CancellationTokencancellationToken=default)=>InnerAgent.RunAsync(messages,session,options,cancellationToken);protectedoverrideIAsyncEnumerable<AgentResponseUpdate>RunCoreStreamingAsync(IEnumerable<ChatMessage>messages,AgentSession?session=null,AgentRunOptions?options=null,CancellationTokencancellationToken=default)=>InnerAgent.RunStreamingAsync(messages,session,options,cancellationToken);}

多个DelegatingAIAgent和最终的被委托的AIAgent按照顺序组成了一个AIAgent管道，这个管道的结构如下所示。

从定义可以看出，以DelegatingAIAgent形式定义的AIAgent中间件并非专属于ChatClientAgent，理论上它可以用于任何类型的AIAgent对象。

2. AIAgentBuilder

系统按照ChatClientBuilder一样的模式定义了AIAgentBuilder。我们可以针对一个具体的AIAgent或者创建AIAgent的工厂来构建一个AIAgentBuilder对象，然后通过调用AIAgentBuilder的一系列重载的Use方法来注册不同的AIAgent中间件，最后调用Build方法来构建出一个代表整个管道的AIAgent对象。

publicsealedclassAIAgentBuilder{publicAIAgentBuilder(AIAgentinnerAgent);publicAIAgentBuilder(Func<IServiceProvider,AIAgent>innerAgentFactory);publicAIAgentBuild(IServiceProvider?services=null);publicAIAgentBuilderUse(Func<AIAgent,AIAgent>agentFactory);publicAIAgentBuilderUse(Func<AIAgent,IServiceProvider,AIAgent>agentFactory);publicAIAgentBuilderUse(Func<IEnumerable<ChatMessage>,AgentSession?,AgentRunOptions?,Func<IEnumerable<ChatMessage>,AgentSession?,AgentRunOptions?,CancellationToken,Task>,CancellationToken,Task>sharedFunc);publicAIAgentBuilderUse(Func<IEnumerable<ChatMessage>,AgentSession?,AgentRunOptions?,AIAgent,CancellationToken,Task<AgentResponse>>?runFunc,Func<IEnumerable<ChatMessage>,AgentSession?,AgentRunOptions?,AIAgent,CancellationToken,IAsyncEnumerable<AgentResponseUpdate>>?runStreamingFunc);}

3. 系统预定义的AIAgent中间件

与IChatClient中间件通过对LLM调用的前后进行增强和控制一样，AIAgent中间件则是通过对AIAgent调用的前后进行增强和控制来实现的。系统预定义了一系列的AIAgent中间件，涵盖了从请求消息的增强、模型响应的增强、工具调用的增强、异常处理、日志记录、性能监控到会话持久化等多个方面。以下列出了一些典型的AIAgent中间件，我会在后续的文章中对它们进行详细的介绍：

MessageAIContextProviderAgent：MessageAIContextProviderAgent是对一组MessageAIContextProvider的包装，它利用重写的RunCoreAsync和RunCoreStreamingAsync方法来调用MessageAIContextProvider针对请求消息的增强以及针对响应消息的增强和处理异常;
FunctionInvocationDelegatingAgent：利用提供的委托可以在某个工具的执行前后注入自定义的逻辑，也可以接管某个工具的调用；
AIHostAgent：通过为为AIAgent绑定了一个AgentSessionStore用来持久化会话状态，使之成为一个具有会话持久化与线程恢复能力的AIAgent；
LoggingAgent：负责拦截内部Agent的各种生命周期操作（如发送请求、模型响应、工具调用），并将这些细节高效、结构化地输出到.NET标准的ILogger日志管道中；
OpenTelemetryAgent：它实现了OpenTelemetry，能够将Agent在推理、工具调用及多轮协作中的各种行为，转化为标准化的Trace链路追踪）、Metrics（指标度量）和 Logs（日志），输出给云端或本地的现代观测后端；
FundtryAgent：是微软Agent框架中连接本地代码与Azure AI Foundry云端托管服务的平台级桥梁组件。它采用定义在云、消费在本地的架构，Agent的提示词、模型参数和工具资产（如代码解释器、文件检索）全部在云端进行可视化管理与安全执行。本地代码只需通过 Agent ID即可直接对其进行实例化；
EntityAgentWrapper：基于Azure Durable Functions或Durable Task Scheduler的底层技术，为Agent披上了一层防弹衣。它把一个普通的 AIAgent（例如 ChatClientAgent）封装为一个受持久化框架管理的有状态实体。它的核心职责是将普通的无状态Agent包装为长生不老的有状态持久化实体，使其能够跨越服务器崩溃、重启或数周的人工审批流，自动实现状态恢复与断点续传;