Microsoft Agent Framework技能系统开发指南

1. Microsoft Agent Framework 技能体系概述

Microsoft Agent Framework 是一个用于构建智能代理应用的开发框架，其核心功能之一就是技能（Skills）系统。技能是指令、脚本和资源的可移植包，能够为代理提供特定领域的功能和专业知识。这套系统遵循开放规范，采用渐进式披露模式，使得代理可以按需加载所需功能。

在实际开发中，技能通常包含以下几个核心组件：

• 前端元数据（Frontmatter）：定义技能名称、描述等基本信息
• 指令说明（Instructions）：指导代理何时以及如何使用该技能
• 资源（Resources）：提供技能运行所需的静态或动态数据
• 脚本（Scripts）：包含可执行的操作逻辑

2. 技能脚本的创建与执行

2.1 基本脚本定义

在C#中，我们可以使用[AgentSkillScript]特性来定义技能脚本。以下是一个单位转换脚本的完整示例：

csharp复制internal sealed class UnitConverterSkill : AgentClassSkill<UnitConverterSkill>
{
    [AgentSkillScript("convert")]
    [Description("Multiplies a value by a conversion factor")]
    private static string ConvertUnits(double value, double factor)
    {
        double result = Math.Round(value * factor, 4);
        return JsonSerializer.Serialize(new { value, factor, result });
    }
}

这个脚本接收两个参数（值和转换系数），执行乘法运算后返回JSON格式的结果。关键点在于：

1. [AgentSkillScript]特性标记了这是一个可执行的技能脚本
2. 方法参数会自动转换为强类型
3. 返回值会被自动序列化传递给调用方

2.2 Python中的脚本定义

Python中使用装饰器语法定义脚本更加简洁：

python复制from agent_framework import ClassSkill

class UnitConverterSkill(ClassSkill):
    @ClassSkill.script(name="convert", description="Unit conversion")
    def convert_units(self, value: float, factor: float) -> str:
        result = round(value * factor, 4)
        return json.dumps({"value": value, "factor": factor, "result": result})

Python实现的注意事项：

• 使用@ClassSkill.script装饰器替代C#的特性语法
• 类型注解不是必须的，但强烈推荐添加以提高可靠性
• 返回值需要手动序列化为字符串

3. 脚本执行的高级配置

3.1 脚本执行权限控制

默认情况下，所有脚本执行都需要显式批准。我们可以通过配置来修改这一行为：

csharp复制var skillsProvider = new