2026年MAF快速入门（23）通过C类定义Skills

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

大家好，我是Edison。

最近我一直在跟着圣杰的《.NET+AI智能体开发进阶》课程学习MAF开发智能体应用，我强烈推荐你也上车跟我一起出发！

MAF 1.1.0 推出了强类型Skill，是的你没有看错，我们可以通过C#类来定义可维护的Skill了。

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

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

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

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

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

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

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

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

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

 
  
    
    
     
     
    " 
   
     
     Microsoft.Agents.AI.OpenAI 
   
     
     " Version= 
   
     
     " 
   
     
     1.1.0 
   
     
     " />

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

internal sealed class UnitConverterSkill : AgentClassSkill 
  
    
     
   
     
      = 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. | | pounds | kilograms | 0. | | 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 + Attribute的声明式组合来实现的。

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

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

这里我们读取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的相关资源都被调用触发，最终完成回复。

问题2：由于问题一已经加载了skill.md和reference文档，它们已经在上下文中了，所以这次直接执行了脚本就完成了回复。

本文介绍了MAF新推出的强类型Skill这个特性，通过类定义Skill可以将资源、脚本、业务规则内聚到一个C#类中，这样就便于代码治理、单元测试与团队协作。

不过，目前MAF的Agent Skills仍然属于实验性支持阶段，生产落地还需谨慎。

GitHub: https://github.com/EdisonTalk/MAFD

圣杰，《.NET + AI 智能体开发进阶》（推荐指数：★★★★★）

Microsoft Learn，《Agent Framework Tutorials》

作者：爱迪生

出处：https://edisontalk.cnblogs.com

本文版权归作者和博客园共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文链接。

2026年MAF快速入门（23）通过C类定义Skills

相关推荐