[MAF的Agent管道详解-06]ChatClientAgent对IChatClient和输入输出增强管道的整合

上面我们介绍了与LLM交互的IChatClient管道、持久化对话消息的ChatHistoryProvider、以及实现输入和输出增强的AIContextProvider接下来我们来看看ChatClientAgent是如何将它们整合在一起的。1. ChatClientAgent的构建如下面的代码片段所示ChatClientAgent定义了两个构造函数我们可以指定一个IChatClient对象、一个ChatClientAgentOptions以及可选的ILoggerFactory和IServiceProvider对象来创建一个ChatClientAgent对象。ChatClientAgentOptions承载的配置选项包括Agent的名称、描述、指令、工具集等也可以通过调用另一个构造函数利用对应的参数来提供。publicsealedclassChatClientAgent:AIAgent{publicIChatClientChatClient{get;}publicChatHistoryProvider?ChatHistoryProvider{get;privateset;}publicIReadOnlyListAIContextProvider?AIContextProviders{get;}protectedoverridestring?IdCore{get;}publicoverridestring?Name{get;}publicoverridestring?Description{get;}publicstring?Instructions{get;}publicChatClientAgent(IChatClientchatClient,string?instructionsnull,string?namenull,string?descriptionnull,IListAITool?toolsnull,ILoggerFactory?loggerFactorynull,IServiceProvider?servicesnull);publicChatClientAgent(IChatClientchatClient,ChatClientAgentOptions?options,ILoggerFactory?loggerFactorynull,IServiceProvider?servicesnull)...1.1 ChatClientAgentOptionsChatClientAgent除ChatClient之外的其他属性都会从ChatClientAgentOptions中获取。如下所示的是ChatClientAgentOptions类型的定义publicsealedclassChatClientAgentOptions{publicstring?Id{get;set;}publicstring?Name{get;set;}publicstring?Description{get;set;}publicChatOptions?ChatOptions{get;set;}publicChatHistoryProvider?ChatHistoryProvider{get;set;}publicIEnumerableAIContextProvider?AIContextProviders{get;set;}publicboolUseProvidedChatClientAsIs{get;set;}publicboolClearOnChatHistoryProviderConflict{get;set;}true;publicboolWarnOnChatHistoryProviderConflict{get;set;}true;publicboolThrowOnChatHistoryProviderConflict{get;set;}true;publicboolRequirePerServiceCallChatHistoryPersistence{get;set;}}具体的配置选项包括IdAgent的唯一标识符如果没有提供系统会自动生成一个GUID字符串作为IdNameAgent的名称用于描述Agent的功能或角色DescriptionAgent的描述信息用于提供更详细的Agent功能说明ChatOptions一个ChatOptions对象调用IChatClient时会使用的选项配置ChatHistoryProvider一个ChatHistoryProvider对象用于管理Agent的对话历史AIContextProviders一个AIContextProvider对象的集合用于提供Agent的上下文定制功能UseProvidedChatClientAsIs一个布尔值指示是否直接使用提供的IChatClient对象而不进行任何包装或增强默认为falseRequirePerServiceCallChatHistoryPersistence一个布尔值指示是否要求每次服务调用都持久化ChatHistoryProvider提供的对话历史默认为false1.2 构建规则ChatClientAgent在构建过程中会采用如下的规则如果指定的ChatClientAgentOptions没有提供ChatHistoryProvider会默认使用InMemoryChatHistoryProvider作为ChatHistoryProvider如果指定的ChatClientAgentOptions的UseProvidedChatClientAsIs属性被设置成True会直接使用提供的IChatClient对象否则会利用配置选项添加响应的中间件默认利用中间件对IChatClient的装饰规则如下自动添加一个FunctionInvokingChatClient中间件来支持函数调用功能正是这个中间件实现ReAct循环ChatClientAgentOptions的Tools属性提供的工具集将会作为FunctionInvokingChatClient的AdditionalTools;如果ChatClientAgentOptions的RequirePerServiceCallChatHistoryPersistence属性被设置成True会自动添加一个PerServiceCallChatHistoryPersistingChatClient中间件。对于每次Agent调用这个中间件都会确保对话历史被持久化。与此同时会屏蔽ChatHistoryProvider针对对话历史的持久化否则就出现了重复的持久化操作如果IChatClient对象已经内置了对话历史管理功能比如采用OpenAI的Responses API指定的ChatClientAgentOptions又同时提供了ChatHistoryProvider此时就会产生冲突ChatClientAgentOptions提供了三个选项来处理这种冲突ClearOnChatHistoryProviderConflict是否直接将ChatClientAgentOptions的ChatHistoryProvider属性设置为Null默认为trueWarnOnChatHistoryProviderConflict是否输出一个警告日志默认为trueThrowOnChatHistoryProviderConflict是否抛出异常默认为true在如下的演示程序中我们调用OpenAIClient的GetResponsesClient方法来获取一个ResponsesClient对象并将它转换成一个IChatClient对象来创建ChatClientAgent。在创建ChatClientAgent时我们提供了一个ChatClientAgentOptions对象并指定了一个InMemoryChatHistoryProvider作为ChatHistoryProvider。usingdotenv.net;usingMicrosoft.Agents.AI;usingMicrosoft.Extensions.AI;usingOpenAI;usingSystem.ClientModel;DotEnv.Load();varmodelEnvironment.GetEnvironmentVariable(MODEL)!;varapiKeyEnvironment.GetEnvironmentVariable(API_KEY)!;varopenAIUrlEnvironment.GetEnvironmentVariable(OPENAI_URL)!;varprompt目前的天气是晴天气温25°C。请给我一些穿衣建议。;varopenAIClientnewOpenAIClient(credential:newApiKeyCredential(key:apiKey),options:newOpenAIClientOptions{EndpointnewUri(openAIUrl)});varchatClientopenAIClient.GetResponsesClient().AsIChatClient(defaultModelId:model);varagentnewChatClientAgent(chatClient:chatClient,options:newChatClientAgentOptions{ChatHistoryProvidernewInMemoryChatHistoryProvider()});varsessionawaitagent.CreateSessionAsync();awaitagent.RunAsync(message:prompt,session:session);我们调用ChatClientAgent的RunAsync方法来发送一个请求消息此时会得到如下所示的InvalidOperationException异常提示ChatClientAgentOptions的ChatHistoryProvider属性与IChatClient对象内置的对话历史管理功能产生了冲突。2. 会话的创建和序列化由ChatClientAgent创建的Session类型为ChatClientAgentSession它在基类AgentSession的基础上增加了一个ConversationId属性用于标识与LLM交互的会话ID。所以ChatClientAgent重写了基类的CreateSessionCoreAsync方法来创建一个ChatClientAgentSession对象并重写了SerializeSessionCoreAsync和DeserializeSessionCoreAsync方法来支持ChatClientAgentSession对象的序列化和反序列化。它还额外提供了一个CreateSessionAsync方法来创建一个带有指定ConversationId的ChatClientAgentSession对象。publicsealedclassChatClientAgent{protectedoverrideValueTaskAgentSessionCreateSessionCoreAsync(CancellationTokencancellationTokendefault);publicValueTaskAgentSessionCreateSessionAsync(stringconversationId,CancellationTokencancellationTokendefault);protectedoverrideValueTaskJsonElementSerializeSessionCoreAsync(AgentSessionsession,JsonSerializerOptions?jsonSerializerOptionsnull,CancellationTokencancellationTokendefault);protectedoverrideValueTaskAgentSessionDeserializeSessionCoreAsync(JsonElementserializedState,JsonSerializerOptions?jsonSerializerOptionsnull,CancellationTokencancellationTokendefault)}publicsealedclassChatClientAgentSession:AgentSession{publicstring?ConversationId{get;set;}}3. 执行流程除了具有专属的AgentSession类型之外ChatClientAgent还有一个属于直接的AgentRunOptions类型名为ChatClientAgentRunOptions。它在基类AgentRunOptions的基础上增加了一个ChatOptions属性返回的ChatOptions将会作为调用IChatClient的GetResponseAsync和GetStreamingResponseAsync方法的参数。另一个ChatClientFactory属性返回的FuncIChatClient, IChatClient委托可以用来为指定的IChatClient对象装饰任意的中间件。如果基于IChatClient的中间件适用于每次调用就应该将它置于预先构建好的IChatClient管道中并利用它来创建ChatClientAgent。如果中间件只适用于某些特殊的调用ChatClientAgentRunOptions的ChatClientFactory赋予我们对它进行动态注册的机会。ChatClientAgent重新定义了一系列重载的RunAsync和RunStreamingAsync方法来接受ChatClientAgentRunOptions参数。publicsealedclassChatClientAgentRunOptions:AgentRunOptions{publicChatOptions?ChatOptions{get;set;}publicFuncIChatClient,IChatClient?ChatClientFactory{get;set;}}publicsealedclassChatClientAgent{publicTaskAgentResponseRunAsync(AgentSession?session,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicTaskAgentResponseRunAsync(stringmessage,AgentSession?session,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicTaskAgentResponseRunAsync(ChatMessagemessage,AgentSession?session,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicTaskAgentResponseRunAsync(IEnumerableChatMessagemessages,AgentSession?session,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicIAsyncEnumerableAgentResponseUpdateRunStreamingAsync(AgentSession?session,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicIAsyncEnumerableAgentResponseUpdateRunStreamingAsync(stringmessage,AgentSession?session,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicIAsyncEnumerableAgentResponseUpdateRunStreamingAsync(ChatMessagemessage,AgentSession?session,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicIAsyncEnumerableAgentResponseUpdateRunStreamingAsync(IEnumerableChatMessagemessages,AgentSession?session,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);执行ChatClientAgent真正的逻辑实现在重写的RunCoreAsync和RunCoreStreamingAsync方法中。publicsealedclassChatClientAgent{protectedoverrideasyncTaskAgentResponseRunCoreAsync(IEnumerableChatMessagemessages,AgentSession?sessionnull,AgentRunOptions?optionsnull,CancellationTokencancellationTokendefault);protectedoverrideIAsyncEnumerableAgentResponseUpdateRunCoreStreamingAsync(IEnumerableChatMessagemessages,AgentSession?sessionnull,AgentRunOptions?optionsnull,CancellationTokencancellationTokendefault);}}我们来具体说说实现在RunCoreAsync方法中的调用流程我们将整个流程分为准备阶段、调用阶段和收尾阶段。准备阶段流程如下如果指定的session为null则调用CreateSessionAsync方法来创建一个新的ChatClientAgentSession对象也就是说孤立的单次调用也会绑定一个Session如果RequirePerServiceCallChatHistoryPersistence选项为false会利用ChatHistoryProvider加载作为当前对话历史的消息列表并与指定的消息列表进行合并如果为true额外注册的PerServiceCallChatHistoryPersistingChatClient会在每次调用时完成此工作根据得到的消息列表和从ChatOptions提取的系统指令和工具集创建AIContext上下文并基于它调用每个注册的AIContextProvider的InvokingAsync方法来定制这个上下文。被定制的系统指令和工具集最终回ChatOptions中从而实现针对输入的增强如果指定的AgentRunOptions参数是一个ChatClientAgentRunOptions对象并且它的ChatClientFactory属性不为null会将当前IChatClient作为参数调用这个ChatClientFactory委托对它进行装饰以得到一个新的IChatClient对象来调用否则直接使用ChatClientAgent的ChatClient属性来调用。调用之后进入收尾阶段如果调用过程没有发生异常并得到作为响应结果的ChatResponse则按照如下的流程执行如果ChatResponse的ContinuationToken不为null意味这得到的并非完整的结果还有后续在RequiresPerServiceCallChatHistoryPersistenceFalse的情况下如果为True的化额外注册的PerServiceCallChatHistoryPersistingChatClient会在每次调用时完成此工作需要将响应返回的ConversationId保存到当前ChatClientAgentSession的ConversationId属性上如果响应消息的AuthorName属性没有设置会设置为当前ChatClientAgent的Name属性如果RequirePerServiceCallChatHistoryPersistence选项为false并且ChatResponse的ContinuationToken不为null或者chatOptions.AllowBackgroundResponses为True表明响应尚未结束此时需要将响应消息列表与当前对话历史进行合并后存储到ChatHistoryProvider中调用每个注册的AIContextProvider的InvokedAsync方法来对结果进行再加工如果调用过程中发生了异常并且RequirePerServiceCallChatHistoryPersistence选项为False此时需要调用每个注册的AIContextProvider的InvokedAsync方法来作响应的异常处理调用每个注册的AIContextProvider的InvokedAsync方法来作响应的异常处理对于RunCoreStreamingAsync方法调用流程与RunCoreAsync方法基本一致区别在于它会处理来自IChatClient的流式响应并将每个响应更新AgentResponseUpdate逐一返回。如果Agent执行尚未结束响应的ChatResponse或者ChatResponseUpdate的ContiuationToken属性将会返回一个ResponseContinuationToken对象。如果希望得到后续的响应需要指定一个ChatClientAgentRunOptions对象并将这个ContinuationToken对象保存到ChatClientAgentRunOptions对象的ContinuationToken属性中。对于ChatClientAgent来说这个ContinuationToken是一个ChatClientAgentContinuationToken对象。从如下的代码可以看出ChatClientAgentContinuationToken是对另一个ResponseContinuationToken对象的包装并在此基础上增加了InputMessages和ResponseUpdates属性来保存之前的输入消息列表和响应更新列表以便在获取后续响应时继续使用。internalclassChatClientAgentContinuationToken:ResponseContinuationToken{internalResponseContinuationTokenInnerToken{get;}internalIEnumerableChatMessage?InputMessages{get;set;}internalIReadOnlyListChatResponseUpdate?ResponseUpdates{get;set;}internalChatClientAgentContinuationToken(ResponseContinuationTokeninnerToken);}4. 结构化输出让Agent返回指定结构的输出一直是Agent开发中的一个重要需求。ChatClientAgent通过提供一系列重载的RunAsync方法来满足这个需求这些方法允许调用者指定一个泛型参数T来表示期望的响应结果类型。ChatClientAgent会尝试将LLM的响应内容反序列化成T类型的对象并将其封装在AgentResponseT对象中返回。publicsealedclassChatClientAgent:AIAgent{publicTaskAgentResponseTRunAsyncT(AgentSession?session,JsonSerializerOptions?serializerOptions,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicTaskAgentResponseTRunAsyncT(stringmessage,AgentSession?session,JsonSerializerOptions?serializerOptions,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicTaskAgentResponseTRunAsyncT(ChatMessagemessage,AgentSession?session,JsonSerializerOptions?serializerOptions,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);publicTaskAgentResponseTRunAsyncT(IEnumerableChatMessagemessages,AgentSession?session,JsonSerializerOptions?serializerOptions,ChatClientAgentRunOptions?options,CancellationTokencancellationTokendefault);}结构化输出的核心是对AgentRunOptions的ResponseFormat属性进行配置该属性定义了LLM响应内容的期望格式。通过设置ResponseFormat开发者可以指定响应应如何被序列化和反序列化从而确保Agent返回的数据结构符合预期。