Bitzsoft.Integrations.AgentFramework 1.0.0-alpha.7

Bitzsoft.Integrations.AgentFramework

AI Agent 框架，基于 Microsoft Semantic Kernel 的智能对话代理，提供多轮对话、流式输出与会话持久化能力。

功能特性

• 基于 Microsoft Semantic Kernel 构建，Kernel 通过 DI 容器注册（微软最佳实践）
• 兼容 OpenAI API 端点（OpenAI、DeepSeek、通义千问等）
• 单轮对话与流式响应（IAsyncEnumerable<string>）
• 多轮对话支持，内置 ChatHistory 管理
• 会话持久化：通过 IChatSessionStore 跨请求保存/恢复聊天历史，实现连续多轮对话记忆
• 可自定义系统提示词，内置法律助手、通用助手、文档分析等预设角色
• 依赖注入友好，一行代码完成服务注册
• HttpClient 已接入 Bitzsoft.Integrations.RequestLogging 第三方请求日志

安装

dotnet add package Bitzsoft.Integrations.AgentFramework

或直接在项目文件中添加：

<PackageReference Include="Bitzsoft.Integrations.AgentFramework" Version="*" />

配置

在 appsettings.json 中添加以下配置节：

{
  "AgentOptions": {
    "Enabled": true,
    "Endpoint": "https://api.openai.com/v1",
    "ApiKey": "sk-your-api-key",
    "ModelId": "gpt-4o",
    "SystemPrompt": "你是一个有帮助的 AI 助手。"
  }
}

AgentOptions 继承自 AiOptions（Bitzsoft.Integrations.AI.Abstractions），共享 Endpoint / ApiKey / ModelId / SystemPrompt 字段。

注册服务

在 Program.cs 中注册 Agent 服务：

using Bitzsoft.Integrations.AgentFramework.Dto;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// 方式一：从 appsettings.json 绑定配置
builder.Services.AddAIAgent(options =>
    builder.Configuration.GetSection("AgentOptions").Bind(options));

// 方式二：代码内直接配置
builder.Services.AddAIAgent(options =>
{
    options.Enabled = true;
    options.Endpoint = "https://api.openai.com/v1";
    options.ApiKey = "sk-your-api-key";
    options.ModelId = "gpt-4o";
    options.SystemPrompt = "你是一个有帮助的 AI 助手。";
});

第三方请求日志

机制说明：本连接器基于 Microsoft Semantic Kernel Agent Framework，HTTP 管道封装在 Agent 的底层连接器内部，无法用 DelegatingHandler 拦截（与 HttpClient 直连实现不同）。请求日志改由 IRequestLogRecorder 回调钩子实现：在 Agent 调用包装层记录每次会话交互，汇入与 HttpClient 拦截同一个日志管道（IRequestLogStore），由宿主统一持久化。

记录内容（每次 Agent 交互产生一条）：

局限：

• Agent Framework 不暴露原始 HTTP 状态码与响应头，无法像 HttpClient 拦截那样记录真实 HTTP StatusCode/RequestHeaders，StatusCode 在成功时记 200，异常时留空。
• 仅本连接器实现的会话交互操作会被记录；Agent 的其他能力（如内部插件调用、记忆等，本连接器未单独包装）不在记录范围。

// ① 默认：启用回调但不持久化（日志丢弃）
builder.Services.AddAIAgent(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，Agent 调用自动落库
//    AddAIAgent 内部已注入 IRequestLogRecorder，宿主无需再额外挂载 handler
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 0;               // 模型响应可能很长，0=不截断完整保留
    opts.SensitiveFields.Add("mySecret"); // 额外脱敏字段
});
builder.Services.AddAIAgent(options => { /* ... */ });

自定义 IRequestLogStore 实现（SqlSugar / Dapper / MongoDB）详见 Bitzsoft.Integrations.RequestLogging。

使用示例

单轮对话

using Bitzsoft.Integrations.AgentFramework.Const;
using Bitzsoft.Integrations.AgentFramework.Interfaces;

public class LegalConsultationService
{
    private readonly IAgentService _agent;

    public LegalConsultationService(IAgentService agent)
    {
        _agent = agent;
    }

    public async Task<string> AskLegalQuestionAsync(string question, CancellationToken ct = default)
    {
        // 使用内置法律助手提示词
        var answer = await _agent.SendMessageAsync(
            message: question,
            systemPrompt: SystemPrompts.LegalAssistant,
            cancellationToken: ct);

        return answer;
    }
}

流式响应

using System.Runtime.CompilerServices;
using Bitzsoft.Integrations.AgentFramework.Const;
using Bitzsoft.Integrations.AgentFramework.Interfaces;

public class ChatStreamingService
{
    private readonly IAgentService _agent;

    public ChatStreamingService(IAgentService agent)
    {
        _agent = agent;
    }

    public async IAsyncEnumerable<string> StreamChatAsync(
        string userMessage,
        [EnumeratorCancellation] CancellationToken ct = default)
    {
        await foreach (var chunk in _agent.SendMessageStreamAsync(
            message: userMessage,
            systemPrompt: SystemPrompts.DocumentAnalyzer,
            cancellationToken: ct))
        {
            yield return chunk;
        }
    }
}

多轮对话（带历史记录）

using Bitzsoft.Integrations.AgentFramework.Const;
using Bitzsoft.Integrations.AgentFramework.Interfaces;

public class ConversationService
{
    private readonly IAgentService _agent;

    public ConversationService(IAgentService agent)
    {
        _agent = agent;
    }

    public async Task RunMultiTurnAsync(CancellationToken ct = default)
    {
        // 创建会话历史，指定系统提示词
        var history = _agent.CreateChatHistory(SystemPrompts.GeneralAssistant);

        // 第一轮
        var reply1 = await _agent.ChatWithHistoryAsync(history, "请介绍一下劳动合同法的基本原则", ct);
        Console.WriteLine($"助手: {reply1}");

        // 第二轮 -- 历史记录自动累积，模型可以理解上下文
        var reply2 = await _agent.ChatWithHistoryAsync(history, "那试用期最长是多少个月？", ct);
        Console.WriteLine($"助手: {reply2}");
    }
}

会话持久化（跨请求多轮对话记忆）

AddAIAgent 默认注册内存会话存储（InMemoryChatSessionStore），通过 ChatInSessionAsync 实现跨请求的连续对话：

using Bitzsoft.Integrations.AgentFramework.Interfaces;

public class ChatService(IAgentService agent)
{
    /// <summary>
    /// 基于会话 ID 的持续对话（自动加载/保存历史）
    /// </summary>
    public async Task<string> ChatAsync(string sessionId, string message, CancellationToken ct = default)
    {
        // 首次调用自动创建会话；后续调用自动加载之前的对话历史
        return await agent.ChatInSessionAsync(sessionId, message, ct);
    }
}

分布式部署时，替换为自定义存储（如 Redis）：

// 替换默认的内存存储为 Redis 实现
builder.Services.AddAIAgent(options => { /* ... */ });
builder.Services.AddChatSessionStore<RedisChatSessionStore>();

内置系统提示词

Bitzsoft.Integrations.AgentFramework.Const.SystemPrompts 提供了以下预设角色：

相关包

• Bitzsoft.Integrations.SemanticKernel — Semantic Kernel 基础集成
• Bitzsoft.Integrations.RAG — 检索增强生成（RAG）集成
• Bitzsoft.Integrations.Ocr — OCR 文字识别集成
• Bitzsoft.Integrations.McpServer — MCP 服务端集成，可将 Agent 工具暴露为 MCP 协议端点
• Bitzsoft.Integrations.All — 所有集成包的统一引用