Galosys.Foundation.Agents.AI.Redis 26.10.29.1

dotnet add package Galosys.Foundation.Agents.AI.Redis --version 26.10.29.1
                    
NuGet\Install-Package Galosys.Foundation.Agents.AI.Redis -Version 26.10.29.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Galosys.Foundation.Agents.AI.Redis" Version="26.10.29.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Galosys.Foundation.Agents.AI.Redis" Version="26.10.29.1" />
                    
Directory.Packages.props
<PackageReference Include="Galosys.Foundation.Agents.AI.Redis" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Galosys.Foundation.Agents.AI.Redis --version 26.10.29.1
                    
#r "nuget: Galosys.Foundation.Agents.AI.Redis, 26.10.29.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Galosys.Foundation.Agents.AI.Redis@26.10.29.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Galosys.Foundation.Agents.AI.Redis&version=26.10.29.1
                    
Install as a Cake Addin
#tool nuget:?package=Galosys.Foundation.Agents.AI.Redis&version=26.10.29.1
                    
Install as a Cake Tool

Galosys.Foundation.Agents.AI.Redis

MAF Redis 存储模块,提供两块能力:

  1. 消息级聊天历史(RedisChatHistoryProvider : ChatHistoryProvider):为 ChatClientAgent 持久化/还原对话历史,参考 MAF 官方 Valkey ChatHistoryProvider 思路。
  2. 长记忆(AgentRedisMemoryProvider : AIContextProvider):跨会话沉淀/检索用户画像与事实记忆。

提供程序无关、不依赖 Hosting、不绑定具体 Redis 客户端(仅依赖 Galosys.Foundation.Redis 抽象层 IRedisConnection)。

会话级存储(AgentSessionStore)在独立模块 Galosys.Foundation.Agents.AI.Hosting.EntityFrameworkCore 中。RAG(向量检索,需 Redis Stack/8)属路线图 P2 独立包 Agents.AI.Redis.Rag。

安装

<PackageReference Include="Galosys.Foundation.Agents.AI.Redis" />

存储设计

Redis 结构 Key 说明
List agent:chat:{ConversationId} 每条消息一个元素(完整序列化的 ChatMessage JSON),RPUSH 时序追加,按序还原
  • 会话隔离:每个会话一个 List(Key 后缀 = 存于 StateBag 的 ConversationId)。
  • TTL:每次写入后为 Key 刷新过期时间(滑动过期,默认 7 天)。
  • 上限裁剪:写入后 LTRIM 保留末尾 N 条(默认 100)。
  • 支持 Redis 4/5/6/7(仅用 RPUSH / LRANGE / LTRIM / EXPIRE / DEL 等基础命令,无需 Stream / 模块 / 高版本特性)。

注册

using Microsoft.Extensions.DependencyInjection;

var builder = Host.CreateApplicationBuilder(args);

// 1. 先注册 Redis 连接实现(FreeRedis 或 StackExchange)
builder.Services.AddRedisClient();                          // FreeRedis
// 或 builder.Services.AddRedisCli<StackExchangeRedisCli>(); // StackExchange

// 2. 注册 Redis ChatHistoryProvider
builder.Services.AddRedisChatHistoryProvider(options =>
{
    options.TimeToLive = TimeSpan.FromDays(7);  // 默认 7 天
    options.MaxMessages = 100;                  // 默认 100 条
    // 可选:上下文窗口压缩器(IChatReducer)
    options.ChatReducer = new LastNChatReducer(20);
});

AddRedisChatHistoryProvider() 幂等注册 RedisChatHistoryProvider 与 ChatHistoryProvider(Transient,工厂解析 IRedisConnection)。

配置到 Agent

using Microsoft.Agents.AI;

var agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
{
    Name = "assistant",
    ChatOptions = new ChatOptions { Instructions = "You are a helpful assistant." },
    ChatHistoryProvider = provider // 解析 ChatHistoryProvider 注入
});

Options(RedisChatHistoryProviderOptions)

  • StateKey — 存入 AgentSession.StateBag 的状态键,默认 Provider 类型名
  • JsonSerializerOptions — ChatMessage 序列化选项,默认模块自带 Web 默认
  • ChatReducer — IChatReducer,Provide 返回前裁剪上下文窗口(不影响持久化)
  • TimeToLive — 存储 Key 过期时间,默认 7 天;null 不过期
  • MaxMessages — 单会话 List 保留上限,默认 100;null 不裁剪
  • StorageInputRequestMessageFilter / StorageInputResponseMessageFilter / ProvideOutputMessageFilter — 存储/检索过滤
  • StateInitializer — 会话状态初始化器,默认随机会话键

长记忆(AgentRedisMemoryProvider)

跨会话持久化/检索键值记忆,任意 Redis(含 5.0)可用。记忆以 Hash 存储(Key:agent:memory:{Namespace}:{ConversationId}),会话特定键存 AgentSession.StateBag。

注册

using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;

var builder = Host.CreateApplicationBuilder(args);

// 1. 先注册 Redis 连接实现(与聊天历史共用同一套 Redis:Connection 配置)
builder.Services.AddRedisClient();                          // FreeRedis
// 或 builder.Services.AddRedisCli<StackExchangeRedisCli>(); // StackExchange

// 2. 注册长记忆 Provider
builder.Services.AddAgentRedisMemoryProvider(options =>
{
    options.Namespace = "default";       // Key 命名空间段,逻辑分组
    options.TimeToLive = TimeSpan.FromDays(7);  // 默认 7 天
    // 从一次已完成调用提取需沉淀的记忆项(记忆名 → 值)。
    // 注意:MemoryExtractor 必须配置,为 null 时记忆不会落库。
    options.MemoryExtractor = ctx => ctx.ResponseMessages
        .SelectMany(m => m.Contents)
        .OfType<TextContent>()
        .Select(t => new MemoryItem("last-response", t.Text))
        .Take(1);
});

挂载到 Agent

using Microsoft.Agents.AI;

var agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
{
    Name = "assistant",
    ChatOptions = new ChatOptions { Instructions = "You are a helpful assistant." },
    AIContextProviders = new[] { memoryProvider } // 解析 AIContextProvider 注入
});
// 或 AIAgentBuilder.UseAIContextProviders(...)

AddAgentRedisMemoryProvider() 幂等注册 AgentRedisMemoryProvider 与 AIContextProvider(Transient,工厂解析 IRedisConnection)。

Options(RedisMemoryOptions)

  • StateKey — 存入 AgentSession.StateBag 的状态键,默认 Provider 类型名
  • Namespace — 记忆命名空间(Key 段),默认 "default"
  • TimeToLive — 记忆 Key 过期时间,默认 7 天;null 不过期
  • JsonSerializerOptions — 记忆值序列化选项,默认模块自带 Web 默认
  • MemoryExtractor — Func<InvokedContext, IEnumerable<MemoryItem>>,从已完成调用提取记忆;null 不自动沉淀

与 EfCoreChatHistoryProvider 对比

维度 Redis 版 EF Core 版
依赖 Galosys.Foundation.Redis 抽象层 Galosys.Foundation.EntityFrameworkCore
会话键 Redis List Key 后缀 ac.ac_agent_session.ConversationId
有序还原 List 天然时序 AgentMessageEntity.Id 排序
多租户 应用侧自定 Key 命名 IMultiTenancy + 全局过滤
适用场景 高频、低延迟、可过期 事务、关联查询、强一致

命名空间

  • 实现类型 RedisChatHistoryProvider / RedisChatHistoryProviderOptions / RedisProviderState / AgentRedisMemoryProvider / RedisMemoryOptions / RedisProviderMemoryState / MemoryItem 在 Galosys.Foundation.Agents.AI.Redis(域实现,不寄生)。
  • DI 注册扩展 AddRedisChatHistoryProvider() / AddAgentRedisMemoryProvider() 寄生 Microsoft.Extensions.DependencyInjection。

MAF 硬规则

Provider 实例字段只持有 IRedisConnection 与 ProviderSessionState,会话特定状态(会话键、消息计数)一律存入 AgentSession.StateBag,单实例服务多会话不串数据。

依赖

  • Galosys.Foundation.Agents.AI — Agent 核心(ChatHistoryProvider / AIContextProvider 抽象)
  • Galosys.Foundation.Redis — Redis 抽象层(IRedisConnection,不引用具体客户端)
  • Microsoft.Agents.AI — MAF 核心(1.13)
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
26.10.29.1 108 10/29/2026
26.10.20.1 95 10/20/2026
26.10.16.2 103 10/16/2026
26.10.16.1 85 10/16/2026
26.10.9.1 104 10/9/2026
26.10.8.1 95 10/8/2026
26.9.23.1 116 9/23/2026
26.9.16.1 110 9/16/2026
26.9.15.1 103 9/15/2026
26.9.14.1 110 9/14/2026
26.9.10.1 128 9/10/2026
26.9.3.1 120 9/3/2026
26.8.29.1 119 8/31/2026
26.8.26.1 112 8/26/2026
26.8.23.1 121 8/23/2026
26.8.21.1 127 8/21/2026
26.8.20.1 148 8/20/2026
26.8.18.1 125 8/18/2026
26.8.17.1 125 8/17/2026
26.8.13.2 125 8/13/2026
Loading failed