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

大家好我是Edison。最近我一直在跟着圣杰的《.NETAI智能体开发进阶》课程学习MAF开发智能体应用我强烈推荐你也上车跟我一起出发MAF 1.1.0 推出了强类型Skill是的你没有看错我们可以通过C#类来定义可维护的Skill了。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 IncludeMicrosoft.Agents.AI.OpenAI Version1.1.0 /首先我们创建一个class文件命名为UnitConverterSkill内容如下internal sealed class UnitConverterSkill : AgentClassSkillUnitConverterSkill{ 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中的内容都体现出来只不过是通过继承AgentClassSkillT Attribute的声明式组合来实现的。创建中间件为了方便看到Skill调用过程我们实现一个带日志记录的工具调用中间件其作用主要是记录Tool的执行日志也可以方便我们验证Skill是否触发。internal class ToolExecutionLoggingMiddleware{ /// summary /// 简化版函数调用中间件 - 记录 Tool 执行日志 /// /summary public static async ValueTaskobject? ExecuteAsync( AIAgent agent, FunctionInvocationContext context, FuncFunctionInvocationContext, CancellationToken, ValueTaskobject? next, CancellationToken cancellationToken) { Console.WriteLine($\n→ Tool: {context.Function.Name}); var result await next(context, cancellationToken); Console.WriteLine($← Result: {result}); return result; }}创建Agent这里我们来创建Agentvar 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文档它们已经在上下文中了所以这次直接执行了脚本就完成了回复。3 小结本文介绍了MAF新推出的强类型Skill这个特性通过类定义Skill可以将 资源、脚本、业务规则内聚到一个C#类中这样就便于代码治理、单元测试 与 团队协作。不过目前MAF的Agent Skills仍然属于实验性支持阶段生产落地还需谨慎。示例源码Github: https://github.com/EdisonTalk/MAFD参考资料圣杰《.NET AI 智能体开发进阶》