Galosys.Foundation.Agents.AI 26.8.18.1

Galosys.Foundation.Agents.AI

Microsoft Agent Framework (MAF) v1.13 薄包装模块。提供模块自动发现和 AddAIAgent() DI 便利扩展，所有编排/中间件能力直接委托给 MAF。

快速入门

安装

确保 Directory.Packages.props 中已配置 MAF 包版本：

<PackageVersion Include="Microsoft.Agents.AI" Version="1.13.0" />
<PackageVersion Include="Microsoft.Agents.AI.OpenAI" Version="1.13.0" />
<PackageVersion Include="Microsoft.Agents.AI.Anthropic" Version="1.13.0-preview.260703.1" />
<PackageVersion Include="Microsoft.Agents.AI.Workflows" Version="1.13.0" />

注册 Agent

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI;

// 编程式创建 AIAgent
var client = new OpenAIClient(new ApiKeyCredential("sk-xxx"),
    new OpenAIClientOptions { Endpoint = new Uri("https://api.openai.com/v1") });

builder.Services.AddAIAgent(sp =>
    client.GetChatClient("gpt-4o")
        .AsAIAgent(name: "assistant", instructions: "You are a helpful assistant."));

使用 Agent

public class ChatService
{
    private readonly AIAgent _agent;

    public ChatService(AIAgent agent) => _agent = agent;

    public async Task<string> Chat(string message)
    {
        var session = await _agent.CreateSessionAsync();
        var response = await _agent.RunAsync(message, session, null);
        return response.Text;
    }
}

多 Agent 编排（使用 MAF Workflows）

using Microsoft.Agents.AI.Workflows;

// 顺序编排
var workflow = AgentWorkflowBuilder.BuildSequential(
    writerAgent, reviewerAgent);
var result = await workflow.RunAsync("Write a blog post", ct);

// 并发编排
var concurrent = AgentWorkflowBuilder.BuildConcurrent(
    new[] { agent1, agent2, agent3 });
var result = await concurrent.RunAsync("Research topic", ct);

// Handoff 模式
var handoffBuilder = AgentWorkflowBuilder
    .CreateHandoffBuilderWith(triageAgent)
    .HandoffTo(salesAgent, "sales")
    .HandoffTo(supportAgent, "support");
var workflow = handoffBuilder.Build();

Middleware（替代旧的 Step 模式）

// MAF DelegatingAIAgent 实现自定义中间件
public class LoggingAgent : DelegatingAIAgent
{
    private readonly ILogger _logger;

    public LoggingAgent(AIAgent inner, ILogger<LoggingAgent> logger)
        : base(inner) => _logger = logger;

    public override async Task<AgentResponse> RunAsync(
        string input, AgentSession? session, AgentRunOptions? options,
        CancellationToken ct = default)
    {
        _logger.LogInformation("Request: {Input}", input);
        var response = await base.RunAsync(input, session, options, ct);
        _logger.LogInformation("Response: {Text}", response?.Text);
        return response;
    }
}

工具调用

MAF AIAgent.RunAsync() 原生支持 Function Calling。通过 ChatOptions.Tools 传入工具定义即可。

输出护栏（Output Guardrail）

已自本模块下沉至 Core chat 层（Microsoft.Extensions.AI）。agent 级 AddAgentOutputGuardrail / UseOutputGuardrail 已移除，护栏统一改由 Core OutputGuardrailChatClient 承载。

配置创建的 IChatClient 经 AddAI 默认管线自动挂载（EnableOutputGuardrail=true）。也可在独立 ChatClient 上显式装配：

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

var services = new ServiceCollection();

// 1. DI 注册默认评估器（TryAddSingleton，可被自定义实现覆盖）
services.AddOutputGuardrail(options =>
{
    // 敏感词拦截
    options.BlockedKeywords = ["机密", "内部资料"];
    // 白名单覆盖（命中白名单不拦截）
    options.Whitelist = ["机密档案室"];
});

// 2. 挂载到 ChatClient 管线
var sp = services.BuildServiceProvider();
var client = new ChatClientBuilder(chatClient).UseOutputGuardrail(sp).Build(sp);

var response = await client.GetResponseAsync([new ChatMessage(ChatRole.User, "帮我查一下机密项目")]);
// 命中敏感词时抛 OutputGuardrailException（携带评估结果），不返回被拦截文本

评估链由两缝构成：

• 识别缝 IPiiDetector：默认 ParameterStatePiiDetector 直接引用 Core ParameterState.Patterns 常量（Email / ChineseMobile / IdCard / IpV4 等），护栏内不复制正则字面量，保证单一事实来源。
• 处理缝 IPiiRedactor：默认 PiiTypeRedactor 由 DI 注入官方 Redactor 子类，PII 独立出现时脱敏（记录 MaskedPii）而非拦截。

对话压缩（Compaction）

已自本模块下沉至 Core chat 层（Microsoft.Extensions.AI）。MAF CompactionProvider 薄挂载扩展（AddAgentCompaction / UseCompaction(provider)）已移除，上下文层压缩统一改由 Core CompactionChatClient 承载。

配置创建的 IChatClient 经 AddAI 默认管线自动挂载（EnableCompaction=true）。也可在独立 ChatClient 上显式装配：

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

var services = new ServiceCollection();

// 1. DI 注册压缩选项（默认 MaxMessages=32，超限截断）
services.AddCompaction(o => o.MaxMessages = 32);

// 2. 挂载到 ChatClient 管线（Truncate 或 Summarize）
var sp = services.BuildServiceProvider();
var client = new ChatClientBuilder(chatClient)
    .UseCompaction(o => o.Strategy = CompactionStrategy.Truncate)
    .Build(sp);

两层压缩分工：存储层 IChatReducer（ChatHistoryProviderOptions.ChatReducer）负责确定性裁剪窗口（不耗 LLM）；上下文层 CompactionChatClient 负责消息量超限时的截断/摘要压缩。两者独立可组合，避免同时用两个摘要型压缩。

工具级指标（OpenTelemetry）

为 Agent 的工具调用记录成功率/耗时/错误率指标（agent.tool.calls / agent.tool.duration），经 System.Diagnostics.Metrics 输出。

using Galosys.Foundation.Agents.AI;
using Microsoft.Agents.AI;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

// 1. DI 注册工具级指标记录器（TryAddSingleton，可配置 MeterName/Enabled）
services.AddAgentsOpenTelemetry(o => o.MeterName = "Galosys.Foundation.Agents.AI");

// 2. 显式挂载到 Agent 管道（经 FunctionInvocationDelegatingAgentBuilderExtensions.Use 回调）
var sp = services.BuildServiceProvider();
var metrics = sp.GetRequiredService<AgentOpenTelemetryFunctionMetrics>();
var builder = new AIAgentBuilder(innerAgent).UseOpenTelemetryFunction(metrics);
var agent = builder.Build(sp);

• 指标维度：agent.tool.calls（tag tool/result）、agent.tool.duration（tag tool）。
• 不含用户/租户 tag：MAF 1.13.0 函数回调无法访问 AgentSession.StateBag；用户/租户维度由成本报表端点（Hosting.AspNetCore 的 /agents/cost）承担。
• Enabled=false 时直接透传，不记录任何指标。
• 默认 meter 名 Galosys.Foundation.Agents.AI 已由 AddOpenTelemetryCore 默认注册，无需额外配置即可被采集。

事件契约

本模块定义 3 个 MessageBase 事件契约（Galosys.Foundation.Agents.AI.Events），仅定义类型、无生产者中间件：

依赖

Provider 支持