🤩 Agent Skills в .NET: три способа создать, один провайдер для запуска

Когда строишь агента, рано или поздно сталкиваешься с проблемой: навыки разрабатывают разные команды, в разное время, в разных форматах. Microsoft Agent Framework теперь поддерживает три подхода к написанию скиллов и объединяет их в одном провайдере без лишней конфигурации.

Какую боль решает

Раньше приходилось либо ждать, пока всё будет готово, либо переписывать логику под один формат. Теперь можно добавлять навыки постепенно: один пришёл из файловой системы, второй из NuGet-пакета, третий написан прямо в коде как временная заглушка. Агент не различает их — он просто выбирает нужный по контексту.

Три способа создать скилл

1️⃣ Файловый скилл

Навык живёт как директория на диске: SKILL.md с инструкциями, скрипты и референсные документы:

skills/
└── onboarding-guide/
    ├── SKILL.md
    ├── scripts/
    │   └── check-provisioning.py
    └── references/
        └── onboarding-checklist.md

В SKILL.md описываем метаданные и шаги для агента. Провайдер поднимается одной строкой:

var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"),
    SubprocessScriptRunner.RunAsync);

2️⃣ Классовый скилл из NuGet

Команда HR-систем публикует Contoso.Skills.HrEnrollment. Внутри — класс, унаследованный от AgentClassSkill<T>. Ресурсы помечаются атрибутом [AgentSkillResource], скрипты — [AgentSkillScript]. Рефлексия сама находит всё нужное:

public sealed class BenefitsEnrollmentSkill : AgentClassSkill<BenefitsEnrollmentSkill>
{
    public override AgentSkillFrontmatter Frontmatter { get; } = new(
        "benefits-enrollment",
        "Enroll an employee in health, dental, or vision plans.");

    [AgentSkillResource("available-plans")]
    public string AvailablePlans => "...список планов...";

    [AgentSkillScript("enroll")]
    private static string Enroll(string employeeId, string planCode) { ... }
}

3️⃣ Инлайн-скилл

Нужный навык ещё не вышел, а ждать нельзя. Пишем прямо в коде через AgentInlineSkill:

var timeOffSkill = new AgentInlineSkill(
    name: "time-off-balance",
    description: "Calculate remaining vacation and sick days.",
    instructions: "...")
    .AddScript("calculate-balance", (string employeeId, string leaveType) =>
    {
        int remaining = HrDatabase.GetAnnualAllowance(employeeId, leaveType)
                      - HrDatabase.GetDaysUsed(employeeId, leaveType);
        return JsonSerializer.Serialize(new { employeeId, leaveType, remaining });
    });

Когда NuGet-пакет выйдет, то просто убираем строку из билдера. Агент ничего не заметит.

Собираем всё вместе

AgentSkillsProviderBuilder объединяет все три типа:

var skillsProvider = new AgentSkillsProviderBuilder()
    .UseFileSkill(Path.Combine(AppContext.BaseDirectory, "skills"))
    .UseSkill(new BenefitsEnrollmentSkill())
    .UseSkill(timeOffSkill)
    .UseFileScriptRunner(SubprocessScriptRunner.RunAsync)
    .UseScriptApproval(true) // подтверждение перед запуском скриптов
    .Build();

UseScriptApproval(true) добавляет человека в цикл: агент приостанавливается перед каждым запуском скрипта и ждёт одобрения. Полезно там, где скрипты имеют реальные последствия — записывают данные, обращаются к продакшн-инфраструктуре.

Подход удобен тем, что каждый шаг независим. Не нужно согласовывать форматы между командами или держать всё в одном репозитории. Файловые скиллы хорошо подходят для контента, который часто меняется. Классовые — для переиспользуемой логики, которую удобно поставлять как пакет. Инлайновые — для временных заглушек и случаев, когда скилл нужно генерировать динамически из данных.

➡️ Источник | Документация | Примеры на GitHub

📍 Навигация: Вакансии • Задачи • Собесы

🐸 Библиотека шарписта

#il_люминатор