Agent框架持久化设置对ReduceAsync调用时机的影响

本文演示在 Microsoft Agent Framework 中，RequirePerServiceCallChatHistoryPersistence 选项如何影响 ChatReducer 的 ReduceAsync 调用时机，并详细说明在不同应用场景下应当开启或关闭该选项的决策依据。文章发布于 2026 年 6 月 2 日，目前该选项仍属于实验性功能，未来行为可能发生调整。

背景

在 Agent Framework 中，ChatHistoryProvider 负责存储和管理对话历史记录。随着对话轮次不断增加，聊天上下文会逐渐累积，最终可能超出 LLM 的 token 限制。为此，框架提供了 IChatReducer 接口，允许开发者在上下文过长时对消息列表进行裁剪，仅保留最核心的部分。

ChatReducer 的核心方法是 ReduceAsync，它接收当前的完整聊天消息列表，并返回缩减后的列表。那么关键问题来了：ReduceAsync 在什么时刻被触发？是在整个对话过程中仅调用一次，还是在每次 LLM 服务调用（包括工具调用）后都会自动执行？若希望在每次工具调用之后都自动压缩上下文，应该如何配置？

答案取决于 RequirePerServiceCallChatHistoryPersistence 选项的设置。

核心概念

RequirePerServiceCallChatHistoryPersistence 是 ChatClientAgentOptions 中的一个布尔选项，其默认值为 false。该选项控制的是：在一次完整的 Agent 运行过程中，是否在每一次 LLM 服务调用完成后立即进行聊天历史的持久化操作。

持久化聊天历史的流程中自然地包含了调用 ReduceAsync。因此，这个选项实际上间接决定了 ReduceAsync 的调用频率。

• 当设置为 true 时：每次 LLM 服务调用完成后，都会触发一次 ReduceAsync。这意味着在多轮工具调用场景中，每完成一次工具调用往返，上下文就会被裁剪一次，从而有效防止中间消息的过度堆积。
• 当设置为 false（默认值）时：ReduceAsync 仅在对话流程的初始阶段被调用，不会在每次工具调用后触发。因此在多轮工具调用的过程中，中间消息会持续累积，可能导致上下文膨胀。

为了更直观地展示这一差异，下面搭建一套可控的演示环境。

搭建演示环境

真实 LLM 的工具调用行为具有不确定性，不利于精确对比。本演示采用自定义的 FakeChatClient 来模拟 LLM，从而精确控制返回的工具调用序列。

FakeChatClient 的设计

FakeChatClient 实现了 IChatClient 接口，其核心思路是通过委托注入响应流，使测试代码能够完全控制 LLM 返回的内容。

public sealed class FakeChatClient : IChatClient
{
    public Func, ChatOptions?, CancellationToken, IAsyncEnumerable>? OnGetStreamingResponseAsync { get; set; }
    public IAsyncEnumerable GetStreamingResponseAsync(
        IEnumerable messages,
        ChatOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        if (OnGetStreamingResponseAsync is null)
        {
            throw new InvalidOperationException($"{nameof(FakeChatClient)}.{nameof(OnGetStreamingResponseAsync)} has not been configured.");
        }
        return OnGetStreamingResponseAsync(messages, options, cancellationToken);
    }
    // ... 其他接口成员的委托注入实现
}

FakeChatClient 为 IChatClient 的每个核心方法都暴露了一个可设置的委托属性。当外部调用这些方法时，实际执行的是对应的委托。这种设计在单元测试和演示场景中非常实用——开发者可以完全控制 ChatClient 的行为，而无需依赖 Mock 框架。对于非流式调用、GetService 和 Dispose 等方法，也提供了相应的委托注入点，确保行为完整。

模拟工具调用序列

为了让演示更贴近真实场景，我们设计了一个会触发两次工具调用的 FakeChatClient。核心逻辑封装在 CreateToolCallingFakeChatClient 方法中。

private static FakeChatClient CreateToolCallingFakeChatClient(int maxToolCallRounds)
{
    var callCount = 0;
    var fakeChatClient = new FakeChatClient()
    {
        OnGetStreamingResponseAsync = (messages, options, cancellationToken) => CreateResponseSequenceAsync()
    };
    return fakeChatClient;

    async IAsyncEnumerable CreateResponseSequenceAsync()
    {
        var currentCall = Interlocked.Increment(ref callCount);
        if (currentCall <= maxToolCallRounds)
        {
            var toolName = currentCall == 1 ? nameof(GetWeather) : nameof(GetTime);
            var callId = $"call_{currentCall}";
            yield return new ChatResponseUpdate(
                ChatRole.Assistant,
                new List()
                {
                    new FunctionCallContent(callId, toolName, new Dictionary()
                    {
                        { "location", "深圳" }
                    })
                })
            {
                FinishReason = ChatFinishReason.ToolCalls,
            };
        }
        else
        {
            yield return new ChatResponseUpdate(
                ChatRole.Assistant,
                "根据查询结果，今天深圳是晴天，气温 25°C，现在时间是 " + DateTime.Now.ToString("HH:mm:ss") + "。")
            {
                FinishReason = ChatFinishReason.Stop,
            };
        }
    }
}

这段代码的设计思路：通过闭包变量 callCount 维护调用计数，并使用 Interlocked.Increment 确保线程安全。前 maxToolCallRounds 次（本演示中为 2 次）LLM 请求返回 FinishReason 为 ToolCalls 的响应，分别触发 GetWeather 和 GetTime 工具调用。第 3 次及之后的 LLM 请求返回 FinishReason 为 Stop 的最终文本回复。这样一条用户消息会触发如下链路：用户消息 → LLM 请求返回“调用 GetWeather”→ 框架执行 GetWeather → LLM 请求返回“调用 GetTime”→ 框架执行 GetTime → LLM 请求返回最终文本。

两个模拟工具方法

GetWeather 和 GetTime 是两个简单的模拟工具方法，在控制台输出调用信息后返回固定字符串。

private static string GetWeather()
{
    Console.WriteLine($"[工具调用] GetWeather 被执行，返回：晴天 25°C");
    return "晴天，25°C";
}
private static string GetTime()
{
    var time = DateTime.Now.ToString("HH:mm:ss");
    Console.WriteLine($"[工具调用] GetTime 被执行，返回：{time}");
    return time;
}

这两个工具方法通过 AIFunctionFactory.Create 注册到 Agent 的 ChatOptions.Tools 列表中。框架会在收到 FinishReason 为 ToolCalls 的响应后自动查找并执行对应的工具方法。

LoggingChatReducer 的设计

为了观察 ReduceAsync 的调用时机，我们实现了一个带有日志输出的 IChatReducer。

sealed class LoggingChatReducer : IChatReducer
{
    private readonly string _name;
    public LoggingChatReducer(string name)
    {
        _name = name;
    }
    public int ReduceCallCount { get; private set; }
    public Task> ReduceAsync(
        IEnumerable messages,
        CancellationToken cancellationToken)
    {
        var messageList = messages.ToList();
        ReduceCallCount++;
        Console.WriteLine($"[{_name}] ReduceAsync 第 {ReduceCallCount} 次被调用，当前消息数：{messageList.Count}");
        if (messageList.Count > 6)
        {
            var reduced = messageList.TakeLast(4).ToList();
            Console.WriteLine($"[{_name}] 上下文消息数从 {messageList.Count} 裁剪为 {reduced.Count}");
            return Task.FromResult>(reduced);
        }
        return Task.FromResult>(messageList);
    }
}

LoggingChatReducer 在两个维度上进行记录：调用次数（通过 ReduceCallCount 属性累计）和裁剪行为（当消息数超过 6 条时只保留最近 4 条，并输出裁剪前后的数量变化）。这里的裁剪策略是简单的“保留最近 N 条”，实际项目中可能需要更智能的策略，例如保留系统消息的同时裁剪历史对话，或基于 token 计数而非消息条数来判断。

演示对比

Main 方法依次运行两个演示，通过相同的 FakeChatClient 和不同的 RequirePerServiceCallChatHistoryPersistence 设置，直观对比 ReduceAsync 的调用频率差异。

演示 1：启用 Persistence

在 DemonstrateWithPersistenceAsync 方法中，创建 Agent 时显式设置 RequirePerServiceCallChatHistoryPersistence 为 true。

var agent = fakeChatClient.AsAIAgent(new ChatClientAgentOptions()
{
    ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions()
    {
        ChatReducer = loggingReducer
    }),
    ChatOptions = new ChatOptions()
    {
        Tools =
        [
            AIFunctionFactory.Create(GetWeather, nameof(GetWeather)),
            AIFunctionFactory.Create(GetTime, nameof(GetTime)),
        ],
    },
    RequirePerServiceCallChatHistoryPersistence = true,
});

InMemoryChatHistoryProvider 是框架内置的内存聊天历史提供程序，ChatReducer 属性用于指定裁剪器实例。运行后控制台输出类似如下：

[演示1-Reducer] ReduceAsync 第 1 次被调用，当前消息数：4
[工具调用] GetWeather 被执行，返回：晴天 25°C
[演示1-Reducer] ReduceAsync 第 2 次被调用，当前消息数：6
[工具调用] GetTime 被执行，返回：15:30:42
[演示1-Reducer] ReduceAsync 第 3 次被调用，当前消息数：8
[演示1-Reducer] 上下文消息数从 8 裁剪为 4

可以看到，ReduceAsync 共计被调用了 3 次：初始阶段 1 次，每次工具调用完成后各 1 次。在第三次调用时，消息数量已超过阈值，触发了裁剪。这意味着启用 Persistence 后，每次工具调用返回的结果和下一轮 LLM 响应都会被及时“收拢”，防止上下文在多次工具调用中无节制地增长。

演示 2：不启用 Persistence（默认）

在 DemonstrateWithoutPersistenceAsync 方法中，不设置 RequirePerServiceCallChatHistoryPersistence（保持默认 false）。

var agent = fakeChatClient.AsAIAgent(new ChatClientAgentOptions()
{
    ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions()
    {
        ChatReducer = loggingReducer
    }),
    ChatOptions = new ChatOptions()
    {
        Tools =
        [
            AIFunctionFactory.Create(GetWeather, nameof(GetWeather)),
            AIFunctionFactory.Create(GetTime, nameof(GetTime)),
        ],
    },
    // RequirePerServiceCallChatHistoryPersistence 默认为 false，不设置
});

运行后控制台输出如下：

[演示2-Reducer] ReduceAsync 第 1 次被调用，当前消息数：3
[工具调用] GetWeather 被执行，返回：晴天 25°C
[工具调用] GetTime 被执行，返回：15:30:42

可以看到，ReduceAsync 仅被调用了 1 次，且发生在对话流程的初始阶段。在后续两次工具调用过程中，ReduceAsync 完全不会被触发。所有中间消息都会累积在 ChatHistoryProvider 中，直到整个对话流程结束。

对比总结

选择哪种设置取决于具体场景：如果 Agent 可能经历多轮工具调用、上下文容易膨胀，建议开启 RequirePerServiceCallChatHistoryPersistence 为 true，让 ReduceAsync 在每次服务调用后及时清理上下文；如果 Agent 工具调用较少、对上下文完整性要求较高，保持默认的 false 可以避免过于频繁的裁剪。

扩展方法：RunStreamingAndLogToConsoleAsync

本演示还定义了一个简化的流式运行扩展方法，将 RunStreamingAsync 的 Text 增量输出到控制台。

public static class AIAgentStreamingExtensions
{
    public static async Task RunStreamingAndLogToConsoleAsync(
        this AIAgent agent,
        IEnumerable messages,
        AgentSession? session = null,
        AgentRunOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        await foreach (var update in agent.RunStreamingAsync(messages, session, options, cancellationToken))
        {
            Console.Write(update.Text);
        }
        Console.WriteLine();
    }
}

由于本演示的核心关注点是 ReduceAsync 的调用时机而非流式输出的细节，这里略去了推理内容（Reasoning）的处理，只将文本内容直接打印到控制台。

关于实验性 API

代码开头有一行 #pragma warning disable MAAI001，这是因为 ChatClientAgentOptions 中的部分 API 目前仍处于实验阶段，编译器会发出 MAAI001 警告。在演示代码中抑制此警告是安全的，但生产环境中请关注官方文档，确认相关 API 已经稳定后再使用。