Microsoft Agent Framework Skills 执行 Scripts（实战指南）

在 Microsoft Agent Framework 中，Agent Skills 是一个非常重要但容易被忽略的能力。它可以让你的 Agent 拥有"插件化能力"，甚至可以执行本地脚本（如 Python），实现真正的自动化。

本文结合完整示例，带你从 原理 → 结构 → 实战 → 坑点 全面掌握如何通过 Skills + 自定义 Tool，实现执行 Python 脚本。

一、什么是 Agent Skills？

官方定义：

Agent Skills 是一组可移植的指令、脚本和资源，用于为 Agent 提供特定能力。

简单理解就是给 Agent 安装"技能包"，比如：

数据分析 skill
报销审核 skill
会议纪要 skill（本文示例）

二、Skill 目录结构

一个标准 Skill 结构如下：

复制代码

skills/
└── meeting-notes/
    ├── SKILL.md
    └── scripts/
        └── GetMeetingNotes.py

1. SKILL.md（核心）

yaml 复制代码

---
name: meeting-notes
description: Various python scripts for meeting-notes
---

md 复制代码

# The meeting notes

[GetMeetingNotes](meeting-notes/scripts/GetMeetingNotes.py)

Give above script-path to a 'execute_python' tool

关键点：

name 必须和目录一致
description 用于让 Agent 判断是否使用该 skill
markdown 内容 = 操作说明

2. Python Script

python 复制代码

def main():
    return "Chester completed the create user api, and need implement the update user api"

if __name__ == "__main__":
    print(main())

说明：

定义 main()
最后 print 输出

三、关键问题：C# 目前不支持自动执行 scripts

官方文档明确说明：

Script execution is not yet supported in C#

所以：

❌ Agent 不会自动执行 .py
✅ 需要自己提供 Tool

四、核心实现：自定义 Python 执行器

PythonRunner.cs

csharp 复制代码

public static class PythonRunner
{
    public static string RunPhytonScript(string pythonFilePath)
    {
        if (string.IsNullOrWhiteSpace(pythonFilePath))
            throw new ArgumentException("File path cannot be empty.", nameof(pythonFilePath));

        pythonFilePath = Path.Combine(AppContext.BaseDirectory, "skills", pythonFilePath);

        if (!File.Exists(pythonFilePath))
            throw new FileNotFoundException("Python file not found.", pythonFilePath);

        if (!string.Equals(Path.GetExtension(pythonFilePath), ".py", StringComparison.OrdinalIgnoreCase))
            throw new ArgumentException("File must have a .py extension.", nameof(pythonFilePath));

        ProcessStartInfo startInfo = new ProcessStartInfo
        {
            FileName = "python",
            Arguments = "\"" + pythonFilePath + "\"",
            UseShellExecute = false,
            RedirectStandardOutput = true,
            RedirectStandardError = true,
            CreateNoWindow = true,
            StandardOutputEncoding = Encoding.UTF8,
            StandardErrorEncoding = Encoding.UTF8
        };

        using (Process process = new Process { StartInfo = startInfo })
        {
            process.Start();

            string output = process.StandardOutput.ReadToEnd();
            string error = process.StandardError.ReadToEnd();

            process.WaitForExit();

            if (process.ExitCode != 0 || !string.IsNullOrWhiteSpace(error))
                throw new InvalidOperationException(
                    "Python script failed. ExitCode=" + process.ExitCode + Environment.NewLine + error.Trim());

            return output.TrimEnd();
        }
    }
}

五、把 Python 执行能力变成 Agent Tool

Program.cs

csharp 复制代码

Tools = [
    AIFunctionFactory.Create(
        PythonRunner.RunPhytonScript,
        name: "execute_python"
    )
]

关键点：

方法暴露为 Tool
名字必须和 SKILL.md 里的说明一致

六、Skills + Tool 协作流程

复制代码

用户输入
   ↓
Agent 发现 skills（Advertise）
   ↓
判断匹配 meeting-notes skill
   ↓
load_skill（加载 SKILL.md）
   ↓
理解指令："调用 execute_python"
   ↓
调用 Tool
   ↓
执行 Python
   ↓
返回结果

七、运行效果

用户输入：

复制代码

帮我获取会议纪要

Agent 内部行为：

发现 meeting-notes
读取 SKILL.md
找到执行说明：

Give above script-path to a 'execute_python' tool
调用：

execute_python("meeting-notes/scripts/GetMeetingNotes.py")

最终输出：

复制代码

Chester completed the create user api, and need implement the update user api

八、关键设计模式

Pattern：Skill 负责"决策"，Tool 负责"执行"

层级	作用
Skill	告诉 Agent 做什么
Tool	真正执行

说明：

Skill ≠ 代码执行
Skill = Prompt + 指南

九、安全建议

执行脚本属于高风险操作，需要注意：

1. 限制路径

csharp 复制代码

skills/xxx

避免执行系统敏感目录，如：

复制代码

../../../../system32

2. 白名单机制

只允许执行：

复制代码

scripts/*.py

3. 沙箱运行

Docker
限制权限
禁止网络访问（必要时）