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

[MAF的Agent管道详解-06]ChatClientAgent对IChatClient和输入输出增强管道的整合
上面我们介绍了与LLM交互的`IChatClient`管道、持久化对话消息的`ChatHistoryProvider`、以及实现输入和输出增强的`AIContextProvider`，接下来我们来看看`ChatClientAgent`是如何将它们整合在一起的。
上面我们介绍了与LLM交互的IChatClient管道、持久化对话消息的ChatHistoryProvider、以及实现输入和输出增强的AIContextProvider，接下来我们来看看ChatClientAgent是如何将它们整合在一起的。

1. ChatClientAgent的构建

如下面的代码片段所示，ChatClientAgent定义了两个构造函数，我们可以指定一个IChatClient对象、一个ChatClientAgentOptions以及可选的ILoggerFactory和IServiceProvider对象来创建一个ChatClientAgent对象。ChatClientAgentOptions承载的配置选项包括Agent的名称、描述、指令、工具集等也可以通过调用另一个构造函数利用对应的参数来提供。
```
public sealed class ChatClientAgent : AIAgent
{    
    public IChatClient ChatClient { get; }
    public ChatHistoryProvider? ChatHistoryProvider { get; private set; }
    public IReadOnlyList? AIContextProviders { get; }
    protected override string? IdCore { get; }
    public override string? Name { get; }
    public override string? Description { get; }
    public string? Instructions { get; }

    public ChatClientAgent(
        IChatClient chatClient,
        string? instructions = null,
        string? name = null,
        string? description = null,
        IList? tools = null,
        ILoggerFactory? loggerFactory = null,
        IServiceProvider? services = null);

    public ChatClientAgent(
        IChatClient chatClient,
        ChatClientAgentOptions? options,
        ILoggerFactory? loggerFactory = null,
        IServiceProvider? services = null)
    ...
```
1.1 ChatClientAgentOptions

ChatClientAgent除ChatClient之外的其他属性都会从ChatClientAgentOptions中获取。如下所示的是ChatClientAgentOptions类型的定义：
```
public sealed class ChatClientAgentOptions
{
    public string? Id { get; set; }
    public string? Name { get; set; }
    public string? Description { get; set; }
    public ChatOptions? ChatOptions { get; set; }
    public ChatHistoryProvider? ChatHistoryProvider { get; set; }
    public IEnumerable? AIContextProviders { get; set; }
    public bool UseProvidedChatClientAsIs { get; set; }
    public bool ClearOnChatHistoryProviderConflict { get; set; } = true;
    public bool WarnOnChatHistoryProviderConflict { get; set; } = true;
    public bool ThrowOnChatHistoryProviderConflict { get; set; } = true;
    public bool RequirePerServiceCallChatHistoryPersistence { get; set; }
}
```
具体的配置选项包括：
- Id：Agent的唯一标识符，如果没有提供，系统会自动生成一个GUID字符串作为Id；
- Name：Agent的名称，用于描述Agent的功能或角色；
- Description：Agent的描述信息，用于提供更详细的Agent功能说明；
- ChatOptions：一个ChatOptions对象，调用IChatClient时会使用的选项配置）；
- ChatHistoryProvider：一个ChatHistoryProvider对象，用于管理Agent的对话历史；
- AIContextProviders：一个AIContextProvider对象的集合，用于提供Agent的上下文定制功能；
- UseProvidedChatClientAsIs：一个布尔值，指示是否直接使用提供的IChatClient对象而不进行任何包装或增强，默认为false；
- RequirePerServiceCallChatHistoryPersistence：一个布尔值，指示是否要求每次服务调用都持久化ChatHistoryProvider提供的对话历史，默认为false；
1.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，默认为true；
- WarnOnChatHistoryProviderConflict：是否输出一个警告日志，默认为true；
- ThrowOnChatHistoryProviderConflict：是否抛出异常，默认为true；
在如下的演示程序中，我们调用OpenAIClient的GetResponsesClient方法来获取一个ResponsesClient对象，并将它转换成一个IChatClient对象来创建ChatClientAgent。在创建ChatClientAgent时，我们提供了一个ChatClientAgentOptions对象，并指定了一个InMemoryChatHistoryProvider作为ChatHistoryProvider。
```
using dotenv.net;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;
using System.ClientModel;

DotEnv.Load();
var model = Environment.GetEnvironmentVariable("MODEL")!;
var apiKey = Environment.GetEnvironmentVariable("API_KEY")!;
var openAIUrl = Environment.GetEnvironmentVariable("OPENAI_URL")!;
var prompt = "目前的天气是晴天，气温25°C。请给我一些穿衣建议。";

var openAIClient = new OpenAIClient(
    credential: new ApiKeyCredential(key: apiKey),
    options: new OpenAIClientOptions
    {
        Endpoint = new Uri(openAIUrl)
    });

var chatClient = openAIClient.GetResponsesClient()
    .AsIChatClient(defaultModelId:model);
var agent = new ChatClientAgent(
    chatClient:chatClient,
    options: new ChatClientAgentOptions { ChatHistoryProvider = new InMemoryChatHistoryProvider() });
var session = await agent.CreateSessionAsync();
await agent.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对象。
```
public sealed class ChatClientAgent
{
    protected override ValueTask CreateSessionCoreAsync(CancellationToken cancellationToken = default);    
    public ValueTask CreateSessionAsync(
        string conversationId,
        CancellationToken cancellationToken = default);
    protected override ValueTask SerializeSessionCoreAsync(
        AgentSession session,
        JsonSerializerOptions? jsonSerializerOptions = null,
        CancellationToken cancellationToken = default);
    protected override ValueTask DeserializeSessionCoreAsync(
        JsonElement serializedState,
        JsonSerializerOptions? jsonSerializerOptions = null,
        CancellationToken cancellationToken = default)
}

public sealed class ChatClientAgentSession : AgentSession
{  
    public string? ConversationId{get;set;}
}
```
3. 执行流程

除了具有专属的AgentSession类型之外，ChatClientAgent还有一个属于直接的AgentRunOptions类型，名为ChatClientAgentRunOptions。它在基类AgentRunOptions的基础上增加了一个ChatOptions属性，返回的ChatOptions将会作为调用IChatClient的GetResponseAsync和GetStreamingResponseAsync方法的参数。另一个ChatClientFactory属性返回的Func委托可以用来为指定的IChatClient对象装饰任意的中间件。

如果基于IChatClient的中间件适用于每次调用，就应该将它置于预先构建好的IChatClient管道中，并利用它来创建ChatClientAgent。如果中间件只适用于某些特殊的调用，ChatClientAgentRunOptions的ChatClientFactory赋予我们对它进行动态注册的机会。ChatClientAgent重新定义了一系列重载的RunAsync和RunStreamingAsync方法来接受ChatClientAgentRunOptions参数。
```
public sealed class ChatClientAgentRunOptions : AgentRunOptions
{
    public ChatOptions? ChatOptions { get; set; }
    public Func? ChatClientFactory { get; set; }
}

public sealed class ChatClientAgent
{
    public Task RunAsync(
        AgentSession? session,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);

    public Task RunAsync(
        string message,
        AgentSession? session,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);

    public Task RunAsync(
        ChatMessage message,
        AgentSession? session,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);

    public Task RunAsync(
        IEnumerable messages,
        AgentSession? session,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);
   
    public IAsyncEnumerable RunStreamingAsync(
        AgentSession? session,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);

    public IAsyncEnumerable RunStreamingAsync(
        string message,
        AgentSession? session,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);

    public IAsyncEnumerable RunStreamingAsync(
        ChatMessage message,
        AgentSession? session,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);

    public IAsyncEnumerable RunStreamingAsync(
        IEnumerable messages,
        AgentSession? session,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);
```
执行ChatClientAgent真正的逻辑实现在重写的RunCoreAsync和RunCoreStreamingAsync方法中。
```
public sealed class ChatClientAgent
{
    protected override async Task RunCoreAsync(
        IEnumerable messages,
        AgentSession? session = null,
        AgentRunOptions? options = null,
        CancellationToken cancellationToken = default);

    protected override IAsyncEnumerable RunCoreStreamingAsync(
        IEnumerable messages,
        AgentSession? session = null,
        AgentRunOptions? options = null,
        CancellationToken cancellationToken = default);
    }
}
```
我们来具体说说实现在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，意味这得到的并非完整的结果，还有后续；在RequiresPerServiceCallChatHistoryPersistence=False的情况下（如果为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属性来保存之前的输入消息列表和响应更新列表，以便在获取后续响应时继续使用。
```
internal class ChatClientAgentContinuationToken : ResponseContinuationToken
{
    internal ResponseContinuationToken InnerToken { get; }
    internal IEnumerable? InputMessages { get; set; }
    internal IReadOnlyList? ResponseUpdates { get; set; }
    internal ChatClientAgentContinuationToken(ResponseContinuationToken innerToken);
}
```
4. 结构化输出

让Agent返回指定结构的输出一直是Agent开发中的一个重要需求。ChatClientAgent通过提供一系列重载的RunAsync方法来满足这个需求，这些方法允许调用者指定一个泛型参数T来表示期望的响应结果类型。ChatClientAgent会尝试将LLM的响应内容反序列化成T类型的对象，并将其封装在AgentResponse对象中返回。
```
public sealed class ChatClientAgent : AIAgent
{  
    public Task<AgentResponse<T>> RunAsync<T>(
        AgentSession? session,
        JsonSerializerOptions? serializerOptions,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);

    public Task<AgentResponse<T>> RunAsync<T>(
        string message, AgentSession? session,
        JsonSerializerOptions? serializerOptions,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);

    public Task<AgentResponse<T>> RunAsync<T>(
        ChatMessage message, AgentSession? session,
        JsonSerializerOptions? serializerOptions,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);

    public Task<AgentResponse<T>> RunAsync<T>(
        IEnumerable messages, AgentSession? session,
        JsonSerializerOptions? serializerOptions,
        ChatClientAgentRunOptions? options,
        CancellationToken cancellationToken = default);
}
```
结构化输出的核心是对AgentRunOptions的ResponseFormat属性进行配置，该属性定义了LLM响应内容的期望格式。通过设置ResponseFormat，开发者可以指定响应应如何被序列化和反序列化，从而确保Agent返回的数据结构符合预期。
相关阅读:
AJAX和JSON
ioctl cmd 不能等于 2 的小问题
 Java中Collections.rotate()方法具有什么功能呢？
MySQL基于GTID搭建主从
 『力扣刷题本』:移除链表元素
 算法笔记—多数相加
 这几种好用的英语图片翻译方法，你们千万不能错过
 命令模式【Java设计模式】
TRex学习之旅四
 【LeetCode】144. 二叉树的前序遍历
原文地址：https://www.cnblogs.com/artech/p/20249982/agent-pipeline-06

1. ChatClientAgent的构建

1.1 ChatClientAgentOptions

1.2 构建规则

2. 会话的创建和序列化

3. 执行流程

4. 结构化输出