Навыки агента

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

Используйте навыки агента, если требуется:

Опыт в области пакетов — захват специализированных знаний (политики расходов, юридических рабочих процессов, конвейеров анализа данных) в качестве многократно используемых переносимых пакетов.
Расширение возможностей агента— предоставление агентам новых возможностей без изменения основных инструкций.
Обеспечение согласованности — преобразование многофакторных задач в повторяемые, проверяемые рабочие процессы.
Включение интероперабельности — повторное использование одного и того же навыка в различных продуктах, совместимых с Agent Skills.

Структура навыка

Умение — это каталог, в котором находится SKILL.md файл с необязательными подкаталогами для ресурсов:

expense-report/
├── SKILL.md                          # Required — frontmatter + instructions
├── scripts/
│   └── validate.py                   # Executable code agents can run
├── references/
│   └── POLICY_FAQ.md                 # Reference documents loaded on demand
└── assets/
    └── expense-report-template.md    # Templates and static resources

формат SKILL.md

Файл SKILL.md должен содержать метаинформацию YAML, за которой следует содержимое markdown:

---
name: expense-report
description: File and validate employee expense reports according to company policy. Use when asked about expense submissions, reimbursement rules, or spending limits.
license: Apache-2.0
compatibility: Requires python3
metadata:
  author: contoso-finance
  version: "2.1"
---

Поле	Обязательно	Description
`name`	Да	Максимум 64 символов. Только строчные буквы, цифры и дефисы. Не должно начинаться или заканчиваться дефисом или содержать последовательные дефисы. Должно соответствовать имени родительского каталога.
`description`	Да	Что делает навык и когда его использовать. Максимум 1024 символов. Следует включать ключевые слова, помогающие агентам определять соответствующие задачи.
`license`	нет	Имя лицензии или ссылка на пакетный файл лицензии.
`compatibility`	нет	Максимум 500 символов. Указывает требования к среде (предназначенный продукт, системные пакеты, сетевой доступ и т. д.).
`metadata`	нет	Произвольное сопоставление значений ключа для дополнительных метаданных.
`allowed-tools`	нет	Список предварительно утвержденных инструментов, разделённый пробелами, которые могут использоваться умением. Экспериментально — уровень поддержки может варьироваться в зависимости от реализации агента.

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

Прогрессивное раскрытие информации

Навыки агента используют трехэтапный прогрессивный шаблон раскрытия для минимизации использования контекста:

Объявление (~100 токенов на навык) — имена и описания навыков внедряются в системный запрос в начале каждого запуска, поэтому агент знает, какие навыки доступны.
Загрузка (< рекомендуется 5000 токенов) — когда задача соответствует сфере навыка, агент вызывает load_skill инструмент для получения полного текста SKILL.md с подробными инструкциями.
Чтение ресурсов (по мере необходимости) — агент вызывает read_skill_resource средство для получения дополнительных файлов (ссылок, шаблонов, ресурсов) только при необходимости.

Этот паттерн сохраняет окно контекста агента компактным, предоставляя ему доступ к обширным специальным знаниям по требованию.

Предоставление навыков агенту

Фреймворк агента включает провайдер навыков, который обнаруживает навыки из каталогов файловой системы и предоставляет их агентам для обеспечения контекста. Он выполняет поиск по настроенным путям рекурсивно (до двух уровней) для SKILL.md файлов, проверяет их формат и ресурсы, а также предоставляет агенту следующие средства: load_skill, read_skill_resource и (когда скрипты присутствуют) run_skill_script.

Замечание

Выполнение скрипта еще не поддерживается в C# и будет добавлено в будущий выпуск.

Базовая настройка

Создайте FileAgentSkillsProvider, указывающий на каталог, содержащий ваши навыки, и добавьте его в контекстные провайдеры агента:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;

// Discover skills from the 'skills' directory
var skillsProvider = new FileAgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));

// Create an agent with the skills provider
AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint), new DefaultAzureCredential())
    .GetResponsesClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "SkillsAgent",
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [skillsProvider],
    });

Вызов агента

После настройки агент автоматически обнаруживает доступные навыки и использует их при совпадении задач:

// The agent loads the expense-report skill and reads the FAQ resource
AgentResponse response = await agent.RunAsync(
    "Are tips reimbursable? I left a 25% tip on a taxi ride.");
Console.WriteLine(response.Text);

Базовая настройка

Создайте SkillsProvider, указывающий на каталог, содержащий ваши навыки, и добавьте его в контекстные провайдеры агента:

from pathlib import Path
from agent_framework import SkillsProvider
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity.aio import AzureCliCredential

# Discover skills from the 'skills' directory
skills_provider = SkillsProvider(
    skill_paths=Path(__file__).parent / "skills"
)

# Create an agent with the skills provider
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
    name="SkillsAgent",
    instructions="You are a helpful assistant.",
    context_providers=[skills_provider],
)

Вызов агента

После настройки агент автоматически обнаруживает доступные навыки и использует их при совпадении задач:

# The agent loads the expense-report skill and reads the FAQ resource
response = await agent.run(
    "Are tips reimbursable? I left a 25% tip on a taxi ride."
)
print(response.text)

Несколько каталогов навыков

Вы можете выполнить поиск по нескольким каталогам, передав список путей:

var skillsProvider = new FileAgentSkillsProvider(
    skillPaths: [
        Path.Combine(AppContext.BaseDirectory, "company-skills"),
        Path.Combine(AppContext.BaseDirectory, "team-skills"),
    ]);

skills_provider = SkillsProvider(
    skill_paths=[
        Path(__file__).parent / "company-skills",
        Path(__file__).parent / "team-skills",
    ]
)

Каждый путь может указывать на отдельную папку навыка (содержащую SKILL.md) или родительскую папку с подкаталогами навыков. Поставщик выполняет поиск до глубины двух уровней.

Пользовательская системная подсказка

По умолчанию поставщик навыков внедряет системный запрос, который перечисляет доступные навыки и указывает агенту использовать load_skill и read_skill_resource. Этот запрос можно настроить:

var skillsProvider = new FileAgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
    options: new FileAgentSkillsProviderOptions
    {
        SkillsInstructionPrompt = """
            You have skills available. Here they are:
            {0}
            Use the `load_skill` function to get skill instructions.
            Use the `read_skill_resource` function to read skill files.
            """
    });

Замечание

Пользовательский шаблон должен содержать заполнитель {0}, в который вставляется список навыков. Литеральные фигурные скобки должны быть экранированы как {{ и }}.

skills_provider = SkillsProvider(
    skill_paths=Path(__file__).parent / "skills",
    instruction_template=(
        "You have skills available. Here they are:\n{skills}\n"
        "Use the `load_skill` function to get skill instructions.\n"
        "Use the `read_skill_resource` function to read skill files."
    ),
)

Замечание

Пользовательский шаблон должен содержать {skills} заполнитель, в который вставляется список навыков, и {runner_instructions} заполнитель, в котором вставляются инструкции, связанные с скриптом.

Определяемые кодом навыки

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

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

Базовый навык кода

Skill Создайте экземпляр с именем, описанием и содержимым инструкций. При необходимости присоединяйте экземпляры SkillResource со статическим контентом:

from textwrap import dedent
from agent_framework import Skill, SkillResource, SkillsProvider

code_style_skill = Skill(
    name="code-style",
    description="Coding style guidelines and conventions for the team",
    content=dedent("""\
        Use this skill when answering questions about coding style,
        conventions, or best practices for the team.
    """),
    resources=[
        SkillResource(
            name="style-guide",
            content=dedent("""\
                # Team Coding Style Guide
                - Use 4-space indentation (no tabs)
                - Maximum line length: 120 characters
                - Use type annotations on all public functions
            """),
        ),
    ],
)

skills_provider = SkillsProvider(skills=[code_style_skill])

Динамические ресурсы

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

import os
from agent_framework import Skill

project_info_skill = Skill(
    name="project-info",
    description="Project status and configuration information",
    content="Use this skill for questions about the current project.",
)

@project_info_skill.resource
def environment() -> Any:
    """Get current environment configuration."""
    env = os.environ.get("APP_ENV", "development")
    region = os.environ.get("APP_REGION", "us-east-1")
    return f"Environment: {env}, Region: {region}"

@project_info_skill.resource(name="team-roster", description="Current team members")
def get_team_roster() -> Any:
    """Return the team roster."""
    return "Alice Chen (Tech Lead), Bob Smith (Backend Engineer)"

Если декоратор используется без аргументов (@skill.resource), имя функции становится именем ресурса, а докстринг становится описанием. Используйте @skill.resource(name="...", description="..."), чтобы задать их явно.

Скрипты, определяемые кодом

Используйте декоратор @skill.script, чтобы зарегистрировать функцию в качестве исполняемого скрипта в навыке. Кодовые скрипты выполняются в процессе и не требуют исполнителя скрипта. Поддерживаются обе функции синхронизации и асинхронной синхронизации:

from agent_framework import Skill

unit_converter_skill = Skill(
    name="unit-converter",
    description="Convert between common units using a conversion factor",
    content="Use the convert script to perform unit conversions.",
)

@unit_converter_skill.script(name="convert", description="Convert a value: result = value × factor")
def convert_units(value: float, factor: float) -> str:
    """Convert a value using a multiplication factor."""
    import json
    result = round(value * factor, 4)
    return json.dumps({"value": value, "factor": factor, "result": result})

Если декоратор используется без аргументов (@skill.script), имя функции становится именем скрипта, а docstring превращается в описание. Типизированные параметры функции автоматически преобразуются в схему JSON, которую агент использует для передачи аргументов.

Объединение навыков на основе файлов и определенных кодом навыков

Передайте оба skill_paths и skills в один SkillsProvider. Сначала обнаруживаются навыки на основе файлов; Если определяемый кодом навык имеет то же имя, что и существующий навык на основе файлов, то кодовый навык пропускается:

from pathlib import Path
from agent_framework import Skill, SkillsProvider

my_skill = Skill(
    name="my-code-skill",
    description="A code-defined skill",
    content="Instructions for the skill.",
)

skills_provider = SkillsProvider(
    skill_paths=Path(__file__).parent / "skills",
    skills=[my_skill],
)

Выполнение сценария

Навыки могут включать исполняемые скрипты, которые агент запускает с помощью средства run_skill_script. Выполнение скрипта зависит от того, как он был определен:

Кодовые скрипты (зарегистрированные с помощью @skill.script) выполняются в процессе в качестве прямых вызовов функций. Не требуется бегун.
Для сценариев на основе файлов (.py файлов, обнаруженных в каталогах навыков) требуется SkillScriptRunner любое вызываемое сопоставление (skill, script, args) -> Any , которое определяет, как выполняется скрипт (например, в качестве локальной подпроцессы).

Выполнение скрипта на основе файлов

Чтобы включить выполнение скриптов на основе файлов, передайте script_runner в SkillsProvider. Может быть использован любой синхронный или асинхронный вызываемый объект, удовлетворяющий протоколу SkillScriptRunner

from pathlib import Path
from agent_framework import Skill, SkillScript, SkillsProvider

def my_runner(skill: Skill, script: SkillScript, args: dict | None = None) -> str:
    """Run a file-based script as a subprocess."""
    import subprocess, sys
    cmd = [sys.executable, str(Path(skill.path) / script.path)]
    if args:
        for key, value in args.items():
            if value is not None:
                cmd.extend([f"--{key}", str(value)])
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
    return result.stdout.strip()

skills_provider = SkillsProvider(
    skill_paths=Path(__file__).parent / "skills",
    script_runner=my_runner,
)

Исполнитель получает разрешенные Skill, SkillScript, и необязательный args словарь. Скрипты на основе файлов автоматически обнаруживаются из .py файлов в каталогах навыков.

Предупреждение

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

Sandboxing (например, контейнеры, seccomp или firejail)
Ограничения ресурсов (процессор, память, тайм-аут по времени)
Проверка входных данных и перечисление исполняемых скриптов
Структурированные журналы и следы аудита

Замечание

Если навыки на основе файлов с скриптами предоставляются, но не script_runner заданы, SkillsProvider вызывает значение ValueError.

Утверждение скрипта

Используйте require_script_approval=True на SkillsProvider для ограничения всех выполнения скриптов человеком. Вместо немедленного выполнения агент приостанавливает и возвращает запросы на утверждение:

from agent_framework import Agent, Skill, SkillsProvider

# Create provider with approval enabled
skills_provider = SkillsProvider(
    skills=[my_skill],
    require_script_approval=True,
)

# Run the agent — script calls pause for approval
result = await agent.run("Deploy version 2.5.0 to production", session=session)

# Handle approval requests
while result.user_input_requests:
    for request in result.user_input_requests:
        print(f"Script: {request.function_call.name}")
        print(f"Args: {request.function_call.arguments}")

        approval = request.to_function_approval_response(approved=True)
        result = await agent.run(approval, session=session)

Если скрипт отклоняется (approved=False), агент уведомляется о том, что пользователь отказался и может отвечать соответствующим образом.

Когда использовать навыки и рабочие процессы

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

Управление — с помощью навыка ИИ решает, как выполнить инструкции. Это идеально, если вы хотите, чтобы агент был творческим или адаптивным. При использовании рабочего процесса вы явно определяете путь выполнения. Используйте рабочие процессы, если требуется детерминированное, прогнозируемое поведение.
Стойкость — навык выполняется в пределах одного хода агента. Если что-то завершается сбоем, необходимо повторить всю операцию. Рабочие процессы поддерживают контрольные точки, чтобы они могли возобновить работу с последнего успешного шага после сбоя. Выберите рабочие процессы, когда стоимость повторного выполнения всего процесса высока.
Побочные эффекты — навыки подходят, когда операции являются идемпотентными или низкорисковыми. Предпочитайте рабочие процессы, когда шаги создают побочные эффекты (отправка сообщений электронной почты, плата за платежи), которые не должны повторяться при повторных попытках.
Сложность — Навыки лучше всего подходят для сконцентрированных задач в одном домене, которые может выполнять один агент. Рабочие процессы лучше подходят для многоэтапных бизнес-процессов, координирующих нескольких агентов, формирование человеческих утверждений и интеграцию с внешними системами.

Подсказка

Как правило, если вы хотите, чтобы ИИ определил, как выполнить задачу, используйте навыки. Если вам нужно гарантировать выполнение шагов и в каком порядке, используйте рабочий процесс.

Дальнейшие шаги

Поставщики контекстов

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-12

Поделиться через

Навыки агента

Структура навыка

формат SKILL.md

Прогрессивное раскрытие информации

Предоставление навыков агенту

Базовая настройка

Вызов агента

Базовая настройка

Вызов агента

Несколько каталогов навыков

Пользовательская системная подсказка

Определяемые кодом навыки

Базовый навык кода

Динамические ресурсы

Скрипты, определяемые кодом

Объединение навыков на основе файлов и определенных кодом навыков

Выполнение сценария

Выполнение скрипта на основе файлов

Утверждение скрипта

Рекомендации по обеспечению безопасности

Когда использовать навыки и рабочие процессы

Дальнейшие шаги

Связанный контент

Обратная связь

Дополнительные ресурсы