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

Конструкція агента — це спосіб створення опорної структури навколо того, як система ШІ діє та мислить, щоб одну базову модель можна було використовувати для багатьох різних завдань. Ця ідея ґрунтується на кількох попередніх концепціях, тож спочатку розглянемо їх: що таке LLM, що таке агент, як поєднуються міркування та використання інструментів, а також які навички є додатковими. Коли це зрозуміло, сама конструкція агента є невеликим кроком, і достатньо простої структури папок, щоб її описати.

Основи

Моделі мови як функції

Для цієї мети LLM можна розглядати як функцію: вхідний текст перетворюється на вихідний текст. Вона лише відповідає на текст текстом, проте більшість сучасних продуктів ШІ будуються на основі саме цієї простої функціональності.

Що вважається агентом

«Агент» — це широке поняття. У наукових працях описується кілька видів агентів, які функціонують зовсім по-різному. Однак у повсякденній розмові майже всі мають на увазі одне: систему чату, яка отримує повідомлення, виконує певні дії та відповідає. Цю схему зазвичай називають 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/

Кожна навичка може мати власні посилання. Навичка соціального сканування може перелічувати акаунти компанії, навичка обробки зображень — місце зберігання готових зображень, а навичка керування блогом — процес публікації. Посилання на рівні комплексу є природним місцем для елементів, які використовуються у всіх трьох сферах, таких як посібники зі стилю та пріоритети бренду:

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

Чому така структура ефективна

Цей формат майже нічого не вимагає від автора. Усе знаходиться у вигляді текстових файлів у папці, що означає, що такий набір можна версіонувати, переглядати та ділитися, як і будь-яким іншим проектом. Агент ніколи не змушений завантажувати всю колекцію, адже кожен описовий файл є невеликим «вказівником», який вирішує, чи продовжувати подальший пошук. Набір для маркетингової команди та набір для адміністратора баз даних відрізняються лише своїм змістом, тоді як процеси пошуку, активації та виконання залишаються ідентичними.

Два звички допомагають підтримувати такий набір у належному стані. По-перше, пишіть кожен опис так, щоб у ньому було зазначено, коли матеріал є актуальним, а не лише що він містить, адже саме з цього речення агент вирішує, що відкрити. По-друге, забезпечуйте справжнє спільне використання посилань на рівні набору. Якщо документ стосується однієї конкретної навички, він має знаходитися всередині цієї навички, а його переміщення вище лише додає «шуму» до всіх інших пошуків.