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（核心）

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

# 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

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

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

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 内部行为：

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

Give above script-path to a 'execute_python' tool

4. 调用：

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

最终输出：

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

八、关键设计模式

Pattern：Skill 负责“决策”，Tool 负责“执行”

说明：

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

九、安全建议

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

1. 限制路径

skills/xxx

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

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

2. 白名单机制

只允许执行：

scripts/*.py

3. 沙箱运行

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