ChatClientAgent自身是对IChatClient对象的封装，后者提供了与LLM交互的能力。在不考虑LLM自身差异的前提下，LLM响应内容的质量和准确性取决于作为输入提供给LLM的消息列表和配置选项，如果能否提供一种灵活的机制动态地定制输入给LLM的消息列表和配置选项，无疑是非常有价值的。另一方面，LLM返回的结果往往也需要经过一些定制化的处理才能满足我们的需求，如果上述的这种机制还能对LLM返回的结果进行定制化处理，那就更加完美了。其实这个机制就实现在ChatClientAgent自身的类型定义上，它位于ChatClientAgent管道中间部分。

如上图所示，这部分主要涉及ChatHistoryProvider和AIContextProvider两个核心组件。前者用于提供和存储基于Session的对话历史，后者可以视为中间件的另一种定义方式：AIContextProvider定义了两个分别在调用IChatClient前后执行的方法(InvokingAsync和InvokedAsync)，前者用来定制传入IChatClient的消息列表和配置选项，后者用来对返回的结果实施再加工。

1. ChatHistoryProvider

当ChatClientAgent以Session的方式被调用时，需要利用ChatHistoryProvider来获取和存储对话历史。ChatHistoryProvider定义了InvokingAsync和InvokedAsync两个方法，前者在调用IChatClient之前被调用，后者在调用IChatClient之后被调用。

public abstract class ChatHistoryProvider
{    
    public ValueTask<IEnumerable<ChatMessage>> InvokingAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);

    public ValueTask InvokedAsync(
        InvokedContext context, 
        CancellationToken cancellationToken = default)
    => InvokedCoreAsync(context, cancellationToken);
}

两个方法都接受一个上下文对象作为其参数，对应的类型InvokingContext和InvokedContext以嵌套的方式定义在ChatHistoryProvider中。

public abstract class ChatHistoryProvider
{
    public sealed class InvokingContext
    {
        public AIAgent Agent { get; }
        public AgentSession? Session { get; }
        public IEnumerable<ChatMessage> RequestMessages{get; set; }
    }

    public sealed class InvokedContext
    {
        public AIAgent Agent { get; }
        public AgentSession? Session { get; }
        public IEnumerable<ChatMessage> RequestMessages { get; }
        public IEnumerable<ChatMessage>? ResponseMessages { get; }
        public Exception? InvokeException { get; }
    }	

上下文数据成员说明如下：

• Agent：当前调用的AIAgent实例；
• Session：当前调用的AgentSession实例；如果当前调用不是基于Session的调用，则该属性为null；
• RequestMessages：当前调用提供的请求消息列表；在InvokingContext中它是一个可读写属性，在InvokedContext中它是一个只读属性；
• ResponseMessages：当前调用得到的响应消息列表；在InvokingContext中不存在，在InvokedContext中它是一个只读属性；如果当前调用过程中发生了异常或者LLM没有返回任何响应消息，则该属性为null；
• InvokeException：当前调用过程中发生的异常；在InvokingContext中不存在，在InvokedContext中它是一个只读属性；如果当前调用过程中没有发生异常，则该属性为null；

ChatHistoryProvider的InvokingAsync和InvokedAsync方法默认会直接点调用InvokingCoreAsync和InvokedCoreAsync方法。ChatHistoryProvider的构造函数还可以提供三个消息过滤器，并且定义了一个用于提供原始对话历史的ProvideChatHistoryAsync方法，以及用于存储对话历史的StoreChatHistoryAsync方法，这些方法都是虚方法，我们可以通过重写这些方法来实现自定义的对话历史获取和存储逻辑。

public abstract class ChatHistoryProvider
{
    protected ChatHistoryProvider(
        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideOutputMessageFilter = null, 
        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputRequestMessageFilter = null, 
        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputResponseMessageFilter = null);

    protected virtual async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);

    protected virtual ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);

    protected virtual ValueTask InvokedCoreAsync(
        InvokedContext context, 
        CancellationToken cancellationToken = default);
    }

    protected virtual ValueTask StoreChatHistoryAsync(
        InvokedContext context, 
        CancellationToken cancellationToken = default);
}

InvokingCoreAsync方法以如下的方法提供对话历史：

• 调用ProvideChatHistoryAsync方法来获取对话历史消息列表；
• 如果构造函数提供了provideOutputMessageFilter过滤器，则调用该过滤器来过滤获取到的对话历史消息列表；
• 将消息来源设置为ChatHistoryProvider，表示消息来源于ChatHistoryProvider提供的对话历史；

InvokedCoreAsync方法以如下的方法存储对话历史：

• 如果调用过程中发生了异常（通过InvokedContext的InvokeException属性判断），则直接返回，不执行任何存储操作；
• 如果构造函数提供了storeInputRequestMessageFilter过滤器，则调用该过滤器来过滤传入的请求消息列表；否则默认过滤掉来源于ChatHistoryProvider的消息，以避免将ChatHistoryProvider提供的请求消息再次保存一遍；
• 如果构造函数提供了storeInputResponseMessageFilter过滤器，则调用该过滤器来过滤传入的响应消息列表；
• 根据过滤后的请求消息列表和响应消息列表创建一个新的InvokedContext对象，并调用StoreChatHistoryAsync方法来存储对话历史；

根据上述的调用流程可以看出，在大部分场景下，自定义的ChatHistoryProvider只需要重写ProvideChatHistoryAsync和StoreChatHistoryAsync方法实现对话历史的加载和存储就可以了。为了避免对消息实施重复存储，InvokingCoreAsync方法会将加载的每个消息的来源都设置成ChatHistoryProvider。消息的来源类型通过如下这个只读结构体AgentRequestMessageSourceType来标记。

public readonly struct AgentRequestMessageSourceType(string value) : IEquatable<AgentRequestMessageSourceType>
{	
    public string Value {get;}
    public static AgentRequestMessageSourceType External { get; } = new AgentRequestMessageSourceType("External");
    public static AgentRequestMessageSourceType AIContextProvider { get; } = new AgentRequestMessageSourceType("AIContextProvider");
    public static AgentRequestMessageSourceType ChatHistory { get; } = new AgentRequestMessageSourceType("ChatHistory");
}

AgentRequestMessageSourceType的三个静态属性分别表示三种具体的来源类型：

• External：来源于外部调用，即用户输入的消息；
• AIContextProvider：来源于注册的AIContextProvider提供；
• ChatHistory：来源于ChatHistoryProvider;

消息的来源存储在表示消息的ChatMessage对象的AdditionalProperties字典中，系统为我们提供了一个扩展方法GetAgentRequestMessageSourceType来获取消息的来源类型，如果没有获取到或者获取到的值不是有效的AgentRequestMessageSourceType，则默认返回External。

public static AgentRequestMessageSourceType GetAgentRequestMessageSourceType(this ChatMessage message);

系统提供了如下几个ChatHistoryProvider的内置实现：

• InMemoryChatHistoryProvider：是ChatHistoryProvider的内存实现版本。它不依赖外部数据库，而是将对话数据存储在当前的进程内存中。它的速度极快，无需配置数据库。但是不可持久化。程序重启后，所有历史记录都会丢失。适合于单元测试、原型开发、或者短期的临时会话；
• CosmosChatHistoryProvider：这是一个生产级的持久化聊天历史管理器实现，专门为Azure Cosmos DB设计。它解决了数据持久化、大规模并发、多租户隔离以及自动清理等核心问题；

2. AIContextProvider

由于ChatClientAgent管道最终会调用IChatClient对象与LLM交互，不论是基于阻断式的GetResponseAsync方法还是基于流式的GetStreamingResponseAsync方法，都只有两个参数：一个是消息列表，一个是ChatOptions对象，这意味着这两个对象完全决定了LLM的响应。为了得到更符合预期的响应，我们就需要对这两个对象进行定制化的处理。在得到了LLM的响应后，我们可能还需要对响应结果进行再加工来满足后续的业务需求。

AIContextProvider就是为了解决这些问题而设计的，它定义了两个方法：PreprocessAsync和PostprocessAsync，前者在调用IChatClient之前被调用，后者在调用IChatClient之后被调用。我们可以通过继承AIContextProvider来实现一个自定义的AI上下文提供者，在PreprocessAsync方法中根据传入的上下文来定制传入IChatClient的消息列表和ChatOptions对象，在PostprocessAsync方法中根据传入的上下文来对返回的结果进行再加工。

如上图所示，所有注册的AIContextProvider构成一个类似于中间件的链条。在调用IChatClient之前，ChatClientAgent会将请求消息列表和从ChatOptions中提取的系统指令与工具集合并成一个AIContext对象，并进一步封装成InvokingContext上下文对象，然后依次调用每个AIContextProvider的InvokingAsync方法对AIContext进行定制。最终交付给IChatClient的消息列表将来源于这个AIContext，采用的ChatOptions也将使用AIContext提供的系统指令。

public sealed class AIContext
{
    public string? Instructions { get; set; }
    public IEnumerable<ChatMessage>? Messages { get; set; }
    public IEnumerable<AITool>? Tools { get; set; }
}

IChatClient调用结束后，得到的结构或者抛出的异常会被封装成一个InvokedContext上下文对象，ChatClientAgent会将此上下文作为参数按照相反的顺序调用每个AIContextProvider的InvokedAsync方法来对结果进行再加工。

public abstract class AIContextProvider
{
    public sealed class InvokingContext
    {
        public AIAgent Agent { get; }
        public AgentSession? Session { get; }
        public AIContext AIContext { get; }
    }

    public sealed class InvokedContext
    {
        public AIAgent Agent { get; }
        public AgentSession? Session { get; }
        public IEnumerable<ChatMessage> RequestMessages { get; }
        public IEnumerable<ChatMessage>? ResponseMessages { get; }
        public Exception? InvokeException { get; }	
    }	

    protected Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> ProvideInputMessageFilter { get; }
    protected Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> StoreInputRequestMessageFilter { get; }
    protected Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>> StoreInputResponseMessageFilter { get; }
    public virtual IReadOnlyList<string> StateKeys {get;}

    protected AIContextProvider(
        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? provideInputMessageFilter = null, 
        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputRequestMessageFilter = null, 
        Func<IEnumerable<ChatMessage>, IEnumerable<ChatMessage>>? storeInputResponseMessageFilter = null);

    public ValueTask<AIContext> InvokingAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);
    protected virtual async ValueTask<AIContext> InvokingCoreAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);
    protected virtual ValueTask<AIContext> ProvideAIContextAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);
    public ValueTask InvokedAsync(
        InvokedContext context, CancellationToken cancellationToken = default);
    protected virtual ValueTask InvokedCoreAsync(
        InvokedContext context, CancellationToken cancellationToken = default);
    protected virtual ValueTask StoreAIContextAsync(
        InvokedContext context, CancellationToken cancellationToken = default);
}

AIContextProvider采用了于ChatHistoryProvider完全一致的定义方式：

• InvokingAsync方法的逻辑：
  • 直接调用虚方法InvokingCoreAsync；
  • InvokingCoreAsync默认会调用ProvideAIContextAsync方法来提供一个AIContext上下文，此上下文将会与作为参数的InvokingContext上下文的AIContext进行合并（具体是对包含在此上下文中的消息列表、系统指令和工具集进行合并）；
  • ProvideAIContextAsync默认返回一个空的AIContext对象，我们可以通过重写ProvideAIContextAsync方法来提供额外的对话历史、系统指令和工具；
• InvokedAsync方法的逻辑：
  • 直接调用虚方法InvokedCoreAsync；
  • InvokedCoreAsync会先检查调用过程中是否发生了异常，如果发生了异常则直接返回；如果没有发生异常，它会调用另一个虚方法StoreAIContextAsync来存储处理后的结果。
  • StoreAIContextAsync默认不执行任何操作，我们可以通过重写StoreAIContextAsync方法来实现自定义的结果存储逻辑；

2.1 MessageAIContextProvider

MessageAIContextProvider派生于AIContextProvider，旨在专门实现针对请求消息（忽略系统指令和工具集）的提供，其使命是将额外的上下文消息（如RAG检索结果、用户画像等）动态地插入到当前的对话流中。它定义了属于自己的InvokingContext上下文，只保留的请求消息列表（剔除了AIContext的Instructions和Tools），

public abstract class MessageAIContextProvider : AIContextProvider
{
    public new sealed class InvokingContext
    {
        public AIAgent Agent { get; }
        public AgentSession? Session { get; }
        public IEnumerable<ChatMessage> RequestMessages { get; }
    }
}

MessageAIContextProvider定义了属于直接的虚方法ProvideMessagesAsync，方法方法以上面定义的InvokingContext上下文作为参数，返回提供的请求消息。重写的ProvideAIContextAsync方法会调用ProvideMessagesAsync来获取额外的请求消息，并将这些消息与原有的请求消息进行合并后返回。

public abstract class MessageAIContextProvider : AIContextProvider
{    
    protected override async ValueTask<AIContext> ProvideAIContextAsync(
        AIContextProvider.InvokingContext context, 
        CancellationToken cancellationToken = default);

    public ValueTask<IEnumerable<ChatMessage>> InvokingAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);

    protected virtual async ValueTask<IEnumerable<ChatMessage>> InvokingCoreAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);

    protected virtual ValueTask<IEnumerable<ChatMessage>> ProvideMessagesAsync(
        InvokingContext context, 
        CancellationToken cancellationToken = default);
}

2.2 预定义的AIContextProvider

系统提供了如下几个MessageAIContextProvider的内置实现：

• ChatHistoryMemoryProvider：可以视为一个非常强大的RAG组件，它将聊天历史转化为了长期记忆，具体来说是将过去的对话记录向量化存入向量数据库，并在后续对话中通过语义搜索找回相关的记忆，以此增强Agent的回答能力；
• TextSearchProvider：它是一个通用型的外部知识搜索插件。如果说ChatHistoryMemoryProvider是Agent的回忆录，那么TextSearchProvider就是Agent的搜索引擎或参考书。它通过封装一个异步搜索函数，实现了RAG架构中检索和注入的标准流程；
• Mem0Provider：这是一个集成了 Mem0 (被称为AI的长期记忆层) 的上下文提供者。与ChatHistoryMemoryProvider相比，Mem0Provider的独特之处在于它不仅仅是存储向量，而是利用Mem0的后端服务来智能提取、更新和关联跨会话的记忆片段；

除了上面几个派生于MessageAIContextProvider的内置实现之外，系统还提供了如下几个AIContextProvider的内置实现：

• AgentSkillsProvider：将Agent Skills引入MAF。在微软的Agent框架中，Skill不仅仅是简单的工具，它是一套领域特定的资产包（包含指令、参考文档、甚至可执行脚本）。这个类的作用是向 Agent 宣告这些技能的存在，并提供动态加载它们的能力;
• CompactionProvider：这是一个专门用于上下文压缩的提供者。它的核心使命是解决大模型上下文窗口限制问题，通过智能压缩历史消息，确保Agent在长对话中既不丢失关键信息，又不超出Token限制；
• FoundryMemoryProvider:这是一个集成了Azure AI Foundry记忆服务的上下文提供者。它的功能定位与Mem0Provider类似，但它属于Azure原生生态，利用AIProjectClient直接与云端托管的记忆库交互；