1 强类型Skill

在写File类型的Skill的时候，我就在想MAF会不会支持强类型Skill，没想到这么快就来了。通过类定义Skill的优势在于强类型、可测试、易分发 等。

类定义Skill的价值在于可以将 资源、脚本、业务规则 内聚到一个C#类中，这样就便于代码治理、单元测试与团队协作。

不过，目前MAF的Agent Skills仍然属于实验性支持阶段，生产落地还需谨慎。这也就意味着，我们需要显示加入 #pragma warning disable MAAI001 这个告警。

2 快速开始：跨境物流运营助手

这里我们来做一个跨境物流运营AI助手，体验一下强类型Skills。

在物流问答场景中，运营人员经常需要：

读取换算规则（资源）
执行换算动作（脚本）
组织可解释的业务回复

在这个案例中，我们可以将上面提到的三类统一内聚到一个类中来管理。

本文案例使用的模型为：Qwen3.5-35B-A3B

在开始之前，我们创建了一个控制台应用，并安装了以下NuGet包：

复制代码

<PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.1.0" />

类定义Skill

首先，我们创建一个class文件命名为UnitConverterSkill，内容如下：

复制代码

internal sealed class UnitConverterSkill : AgentClassSkill<UnitConverterSkill>
{
    public override AgentSkillFrontmatter Frontmatter { get; } = new(
        "unit-converter",
        "Convert between common units using multiplication factors.");
    
    protected override string Instructions => """
        当用户询问距离或重量换算时：
        1. 先读取 conversion-table 资源，找到对应换算系数。
        2. 再调用 convert 脚本执行计算，参数为用户输入的数值value和换算系数factor。
        3. 回复内容需要清晰地展示换算系数、换算过程和换算结果，并同时标明换算前后的两个单位。
        """;
    
    protected override JsonSerializerOptions? SerializerOptions => null;
    
    [AgentSkillResource("conversion-table")]
    [Description("常见距离与重量换算系数表。")]
    public string ConversionTable => """
        # Conversion Table
        Formula: result = value × factor
        | From       | To         | Factor   |
        |------------|------------|----------|
        | miles      | kilometers | 1.60934  |
        | kilometers | miles      | 0.621371 |
        | pounds     | kilograms  | 0.453592 |
        | kilograms  | pounds     | 2.20462  |
        """;

    [AgentSkillScript("convert")]
    [Description("按 value × factor 执行换算，并返回 JSON。")]
    public static string ConvertUnits(double value, double factor)
    {
        double result = Math.Round(value * factor, 4);
        return JsonSerializer.Serialize(new { value, factor, result });
    }
}

可以看到上面的内容其实就是把我们之前在文件skill中的内容都体现出来，只不过是通过继承AgentClassSkill<T> + Attribute的声明式组合来实现的。

创建中间件

为了方便看到Skill调用过程，我们实现一个带日志记录的工具调用中间件，其作用主要是记录Tool的执行日志，也可以方便我们验证Skill是否触发。

复制代码

internal class ToolExecutionLoggingMiddleware
{
    /// <summary>
    /// 简化版函数调用中间件 - 记录 Tool 执行日志
    /// </summary>
    public static async ValueTask<object?> ExecuteAsync(
        AIAgent agent,
        FunctionInvocationContext context,
        Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
        CancellationToken cancellationToken)
    {
        Console.WriteLine($"\n→ 🍴Tool: {context.Function.Name}");
        var result = await next(context, cancellationToken);
        Console.WriteLine($"← 🥣Result: {result}");
        return result;
    }
}

创建Agent

这里我们读取yaml文件内容，并基于yaml来创建Agent：

复制代码

var skillsProvider = new AgentSkillsProvider(new UnitConverterSkill());
AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
    Name = "UnitConverterAgent",
    ChatOptions = new()
    {
        Instructions = "你是一个专业的AI助手，负责帮助用户实现单位的转换，使用用户提问的语言进行回复。",
    },
    AIContextProviders = [skillsProvider],
});
// 💡 使用 Agent Builder 注册函数调用中间件
agent = agent
    .AsBuilder()
    .Use(ToolExecutionLoggingMiddleware.ExecuteAsync) // 使用工具执行日志中间件，记录工具调用的日志
    .Build();
Console.WriteLine("✅ 基于强类型Skills 的 AI Agent 创建成功");
Console.WriteLine();

测试回答问题

这里还是之前的两个问题，一个中文一个英文来测试一下：

复制代码

var session = await agent.CreateSessionAsync();
Console.WriteLine("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
Console.WriteLine($"开始测试：基于 Class-Based Skills");
// 中文问题：英里 -> 公里
var question1 = "马拉松比赛的距离26.2 英里是多少公里？";
Console.WriteLine($"👤 用户: {question1}");
Console.WriteLine();
var response1 = await agent.RunAsync(question1, session);
Console.WriteLine("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
Console.WriteLine($"🤖 Agent: {response1.Text}");
Console.WriteLine("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
Console.WriteLine();
// 英文问题：磅 -> 千克
var question2 = "How many pounds is 75 kilograms?";
Console.WriteLine($"👤 用户: {question2}");
Console.WriteLine();
var response2 = await agent.RunAsync(question2, session);
Console.WriteLine("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
Console.WriteLine($"🤖 Agent: {response2.Text}");
Console.WriteLine("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
Console.WriteLine();

测试结果如下图所示：

**问题1：**可以看到unit-convert skill的相关资源都被调用触发，最终完成回复。