Инструменты агента: стандарт папок для навыков и рекомендаций

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

Основы

Языковые модели как функции

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

Что считается агентом

Термин «агент» имеет широкое значение. В научных работах описывается несколько его видов, которые функционируют совершенно по-разному. Однако в повседневной речи почти все имеют в виду одно и то же: систему чата, которая принимает сообщение, выполняет какие-то действия и отвечает. Такая структура часто называется ReAct — это тонкий слой кода, соединяющий модель с функциональностью, позволяющей ей рассуждать, действовать и наблюдать. ReAct позволяет модели подумать о том, что она собирается сделать, выбрать действие, воздействующее на окружающую среду, а затем получить информацию о результатах. Во всём, что приведено ниже, термин «агент» используется в этом смысле, характерном для подхода ReAct.

Рассуждения и действия

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

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

История использования инструментов схожа: они существуют уже давно, постоянно демонстрируют свою полезность и превращаются в стандарт. В своей наиболее простой форме они указывают модели на то, что если она выдаст определённый фрагмент текста, будет запущен соответствующий код, и вернётся результат. Затем модель решает, когда искать информацию в Интернете, читать файлы или, в худшем случае, отправлять деньги туда, куда не следует. Для решения сложных задач часто требуется сочетание логического мышления и действий, и сравнение стратегий формулировки запросов показывает, что их сочетание эффективнее, чем использование любой из них по отдельности.

Навыки

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

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

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

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

Что такое харнес

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

Формат харнесов агентов

Согласно этому предложенному стандарту, ремень безопасности состоит из трех частей: файла в формате Markdown, описывающего его, набора навыков для взаимодействия с окружением и набора ссылок, помогающих агенту понимать, где он работает. Этот стандарт — это проект с открытым исходным кодом, находящийся в публичном управлении.

my-harness/
├── HARNESS.md        # Required: metadata + instructions
├── skills/           # Optional: a set of skills
└── references/       # Optional: a set of reference documents

Файл высшего уровня HARNESS.md должен быть кратким. Он предоставляет агенту краткий обзор проблемы и указывает, где найти более подробную информацию внутри описаний навыков и ссылок.

Дизайн основан на принципе постепенного раскрытия информации, популяризированном недавно стандартом Agent Skills. Этот процесс происходит в три этапа:

1. Обнаружение. При запуске агент загружает только HARNESS.md, в котором описана структура системы. При поступлении запроса агент сопоставляет его с этими описаниями и постепенно просматривает названия и описания навыков и ссылок, пока не находит необходимую информацию.
2. Активация. После нахождения релевантных материалов загружается и читается полная документация по этим навыкам и ссылкам.
3. Выполнение. Агент действует согласно указаниям системы и может запустить соответствующие навыки.

Файл HARNESS.md

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

---
name: <name of the harness>
description: <description of what the harness is for>
---

<body>

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

Каталог навыков

В этом каталоге хранятся навыки, соответствующие стандарту Agent Skills, который определяет их следующим образом:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

Ремень дополняет это, поэтому каталог навыков выглядит так:

my-harness/
├── HARNESS.md
├── skills/
|  ├── my-skill-1/
|  |  ├── SKILL.md
|  |  ├── scripts/
|  |  ├── references/
|  |  ├── assets/
|  |  └── ...
|  └── my-skill-2/
|     ├── SKILL.md
|     ├── scripts/
|     ├── references/
|     ├── assets/
|     └── ...
└── references/

Каталог ссылок

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

У навыков также есть ссылки, причем эти два уровня отличаются по объёму. Ссылки внутри навыка объясняют, как использовать конкретный навык. Ссылки на уровне платформы должны содержать информацию, необходимую нескольким навыкам, на более высоком уровне абстракции.

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

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/

Каждый навык может иметь свои собственные ссылки. Навык анализа социальных сетей может перечислять аккаунты компании, навык обработки изображений — место хранения готовых изображений, а навык ведения блога — процесс публикации. Ссылки уровня « Harness » представляют собой естественное место для элементов, используемых во всех трех навыках, таких как руководства по стилю и приоритеты бренда:

my-mraketing-harness/
├── HARNESS.md
├── skills/
|  ├── create-blog-post/
|  |  ├── SKILL.md
|  |  └── ...
|  ├── generate-images/
|  |  ├── SKILL.md
|  |  └── ...
|  └── scan-social/
|     ├── SKILL.md
|     └── ...
└── references/
   ├── style-guide.md
   └── brand-priorities.md

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

---
description: a style guide for the marketing website, which covers the creation
of all visual assets and standard typography rules
---

<body>

Организация крупного набора

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

my-harness/
├── HARNESS.md
├── skills/
|  ├── skill1/
|  ├── skill2/
|  ├── skill3/
|  └── ...
└── references/
   ├── reference1
   ├── reference2
   ├── reference3
   └── ...

Ответ — это подкаталоги. В разделах как навыков, так и ссылок папки могут группировать элементы в подмножества:

my-harness/
├── HARNESS.md
├── skills/
│   ├── software-development/
│   │   ├── SKILLS.md
│   │   ├── skill1/
│   │   │   └── SKILL.md
│   │   └── skill2/
│   │       └── SKILL.md
│   ├── market-analysis/
│   │   ├── SKILLS.md
│   │   └── skill3/
│   │       └── SKILL.md
│   └── social-media/
│       ├── SKILLS.md
│       ├── skill4/
│       │   └── SKILL.md
│       └── skill5/
│           └── SKILL.md
└── references/
    ├── brand-assets/
    │   ├── REFERENCES.md
    │   ├── reference1.md
    │   └── reference2.md
    ├── software-infrastructure/
    │   ├── REFERENCES.md
    │   ├── reference3.md
    │   └── reference4.md
    └── product-information/
        ├── REFERENCES.md
        └── reference5.md

Чтобы агент мог полностью, но эффективно понять эту структуру, файл HARNESS.md должен её описывать. Каждый подкаталог также содержит описательный файл: SKILLS.md описывает навыки, находящиеся в подкаталоге, а REFERENCES.md — соответствующие ссылки.

Именно здесь проявляется преимущество постепенного раскрытия информации. Агент сначала читает файл верхнего уровня, чтобы понять общую структуру, а затем открывает конкретные файлы SKILLS.md и REFERENCES.md только тогда, когда это необходимо, что является эффективным способом получения релевантных данных.

Уровни вложенности могут быть настолько глубокими, насколько того требует содержимое, поэтому большой набор материалов можно организовать на высоком уровне. Каждый подкаталог должен содержать собственный файл SKILLS.md или REFERENCES.md, чтобы агент мог понимать каждый уровень по мере его просмотра:

...
└── references/
  └── data-sources/
      ├── REFERENCES.md
      ├── relational/
      │   ├── REFERENCES.md
      │   └── schema-overview.md
      └── warehouse/
          ├── REFERENCES.md
          └── dataset-catalog.md

Почему такая структура эффективна

Этот формат предъявляет к автору минимум требований. Все материалы находятся в виде текстовых файлов в папке, что позволяет версионировать, рассматривать и делиться данными так же, как и любым другим проектом. Агенту никогда не нужно загружать всю коллекцию, поскольку каждый описательный файл служит небольшим указателем, помогающим решить, стоит ли продолжать работу. Инструментарий для маркетинговой команды и инструментарий для администратора баз данных отличаются только содержимым, в то время как процессы поиска, активации и выполнения остаются одинаковыми.

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