Microsoft выпустила стабильный API Agent Skills для Python

Microsoft объявила ^[1] стабильным базовый API Agent Skills для Python в Microsoft Agent Framework. Он позволяет подключать к ИИ-агентам ^[2] переиспользуемые пакеты с инструкциями, справочными материалами и скриптами, которые загружаются по мере необходимости.

Ранее поддержка Agent Skills в Python считалась экспериментальной. Теперь же для использования основного API не требуется включать экспериментальные возможности фреймворка.

Что такое Agent Skills

Agent Skills — открытая спецификация для упаковки предметных знаний и сценариев работы ИИ-агентов. Отдельный навык может включать:

• инструкции для модели;

• справочные документы;

• шаблоны и другие статические ресурсы;

• скрипты, которые агент может запускать при выполнении задачи.

В файловом варианте каждый навык хранится в отдельном каталоге. Основным файлом служит SKILL.md: в нём указываются название, описание и подробные инструкции.

expense-report/
├── SKILL.md
├── references/
│   └── policy.md
├── assets/
│   └── report-template.md
└── scripts/
    └── validate.py

Описание навыка помогает модели определить, подходит ли он для текущей задачи. Дополнительные документы и скрипты не добавляются в контекст заранее.

Подробнее о том, как устроен подход Agent Skills и как с его помощью можно развивать агентов без дообучения, разбирали в отдельном материале. ^[3]

Как загружаются навыки

Agent Skills используют поэтапную загрузку данных.

Сначала агент получает только названия и краткие описания доступных навыков. Когда запрос соответствует одному из них, модель может вызвать инструмент load_skill и загрузить полные инструкции из SKILL.md.

Если для выполнения задачи нужны дополнительные материалы, агент обращается к ним через read_skill_resource. Для запуска входящего в навык скрипта используется run_skill_script.

Получается четыре этапа:

1. Агент узнаёт о доступных навыках.

2. Загружает инструкции выбранного навыка.

3. При необходимости читает справочные материалы.

4. При необходимости запускает скрипты.

Такой подход позволяет не хранить все корпоративные регламенты, инструкции и сценарии в системном промпте и не расходовать контекстное окно на информацию, которая не относится к текущему запросу.

Например, внутреннему помощнику можно подключить отдельные навыки для адаптации новых сотрудников, оформления командировок и проверки требований информационной безопасности. При вопросе о первом рабочем дне агент загрузит инструкции по адаптации, не добавляя в контекст остальные документы.

Три способа описывать навыки

Стабильный API поддерживает три варианта создания Agent Skills.

Файловые навыки хранятся в каталогах с SKILL.md, справочными документами и скриптами. Такой формат подходит для общего репозитория, где инструкции могут поддерживать разные команды.

Навыки на основе классов описываются с помощью Python-классов. Их можно распространять как обычные пакеты, в том числе через внутренний PyPI.

Навыки, определённые в коде, создаются непосредственно внутри приложения. Этот вариант подходит, когда инструкции и ресурсы формируются динамически или зависят от состояния приложения.

Все три вида подключаются через единый поставщик навыков, а для агента выглядят одинаково во время выполнения.

Как подключить Agent Skills

Для файловых навыков используется SkillsProvider. Компонент ищет каталоги с файлами SKILL.md, сообщает агенту о доступных навыках и регистрирует инструменты для загрузки инструкций и ресурсов.

Пример из анонса Microsoft:

import asyncio
import os
from pathlib import Path

from agent_framework import Agent, SkillsProvider
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential


async def main() -> None:
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini"),
        credential=AzureCliCredential(),
    )

    # Ищем файловые навыки в каталоге с файлами SKILL.md.
    # Для доверенных навыков отключаем подтверждение загрузки инструкций
    # и чтения ресурсов. Запуск скриптов по-прежнему требует разрешения.

    skills_dir = Path(__file__).parent / "skills"

    skills_provider = SkillsProvider.from_paths(
        skill_paths=str(skills_dir),
        disable_load_skill_approval=True,
        disable_read_skill_resource_approval=True,
    )

    async with Agent(
        client=client,
        instructions="You are a helpful assistant.",
        context_providers=[skills_provider],
    ) as agent:
        response = await agent.run("Help me with onboarding.")
        print(response.text)


if __name__ == "__main__":
    asyncio.run(main())

Код ожидает, что рядом с приложением находится каталог skills. Каждый его подкаталог с файлом SKILL.md будет обнаружен как отдельный навык.

project/
├── app.py
└── skills/
    └── onboarding/
        ├── SKILL.md
        ├── references/
        │   └── company-policy.md
        └── scripts/
            └── validate.py

В примере клиент модели создаётся через FoundryChatClient. Адрес проекта передаётся в переменной окружения FOUNDRY_PROJECT_ENDPOINT, а модель можно указать через FOUNDRY_MODEL. Для аутентификации используется AzureCliCredential.

Параметры disable_load_skill_approval и disable_read_skill_resource_approval отключают ручное подтверждение только для загрузки инструкций и чтения ресурсов. Автоматического разрешения на запуск скриптов они не дают.

Кроме того, для фактического выполнения файловых скриптов разработчик должен передать в SkillsProvider собственный script_runner. Без него попытка запустить скрипт завершится ошибкой ^[4].

Что предусмотрено для рабочих систем

По умолчанию инструменты load_skill, read_skill_resource и run_skill_script требуют подтверждения. Для доверенных операций разработчик может выборочно отключить его, оставив контроль над действиями с повышенным риском.

Также в API появились:

• фильтрация доступных навыков;

• кэширование;

• объединение навыков из нескольких источников;

• подключение собственных источников и реестров.

Фильтрация позволяет, например, выдавать разным агентам или клиентам разные наборы навыков из общей библиотеки.

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

Что изменилось

Сам механизм Agent Skills существовал в Microsoft Agent Framework и раньше, но Python API находился в экспериментальном статусе. В новом релизе Microsoft объявила стабильными его основные интерфейсы.

Практический смысл обновления — в появлении стандартного способа хранить и распространять инструкции, предметные знания и исполняемые сценарии для агентов. Вместо одного разрастающегося системного промпта команды могут поддерживать отдельные версионируемые пакеты и подключать их к нескольким приложениям.

При этом стабильный статус API не делает содержимое навыков автоматически безопасным. Инструкции, внешние материалы и исполняемый код необходимо проверять так же, как любые другие зависимости, влияющие на поведение ^[5] системы.

Разобраться на практике, как строятся современные ИИ-агенты и какие подходы помогают управлять их возможностями, можно на бесплатных уроках:

• 21 июля, 20:00. «Разработка ИИ-приложений с Claude Code». Записаться ^[6]

• 23 июля, 20:00. «Когнитивные архитектуры: ReAct, Reflection и RAG». Записаться ^[7]