ACE Framework: как правильно описывать инструменты для LLM-агентов

Фреймворк состоит из трёх компонентов:

ОБОГАЩЕНИЕ (выполняется один раз):

1. Парсинг OpenAPI спецификации
2. Генерация описаний методов (из HTTP method, operation ID, параметров)
3. Генерация описаний параметров (из названий, типов, constraints)
4. Генерация примеров параметров (валидные значения для few-shot)

СОЗДАНИЕ ИНСТРУМЕНТОВ (выполняется один раз):

1. Создание Python-функции с декоратором @tool
2. Добавление обогащённого docstring
3. Формирование HTTP-запроса из аргументов

SHORTLISTING (при каждом запросе):

1. Эмбеддинг запроса пользователя
2. Эмбеддинги описаний всех инструментов
3. Semantic search → top-k похожих
4. Загрузка только отобранных инструментов в агента

Задача: Настроить бота-помощника для HR-отдела, который помогает сотрудникам выбрать нужную процедуру.

Промпт без обогащения:

Выбери подходящую процедуру:

1. Оформление отпуска
2. Больничный лист
3. Согласование командировки

Моя ситуация: Еду на конференцию в Питер на 3 дня

Промпт с обогащением (по принципам ACE):

Выбери подходящую процедуру и заполни нужные поля:

**Процедура 1: Оформление отпуска**
Назначение: Ежегодный, учебный или отпуск за свой счёт
Входные данные:
- ФИО сотрудника (строка)
- Даты начала и конца (формат ДД.ММ.ГГГГ)
- Тип отпуска (ежегодный/учебный/за свой счёт)
Пример: "Петров Иван Сергеевич, 01.06.2026-14.06.2026, ежегодный"
Результат: Заявка в 1С, автоматическое уведомление руководителю

**Процедура 2: Оформление больничного**
Назначение: Регистрация листка нетрудоспособности
Входные данные:
- ФИО сотрудника (строка)
- Номер больничного листа (12-значный)
- Даты болезни (формат ДД.ММ.ГГГГ)
Пример: "Сидорова Мария, 123456789012, 15.01.2026-20.01.2026"
Результат: Начисление по больничному в следующей зарплате

**Процедура 3: Согласование командировки**
Назначение: Служебная поездка в другой город с оплатой расходов
Входные данные:
- ФИО сотрудника (строка)
- Город назначения (строка)
- Даты (формат ДД.ММ.ГГГГ)
- Цель поездки (совещание/конференция/переговоры/обучение)
- Бюджет на транспорт (число в рублях)
- Бюджет на проживание (число в рублях, если >1 дня)
Пример: "Козлов Дмитрий, Санкт-Петербург, 10.02.2026-12.02.2026, 
конференция, 15000, 8000"
Результат: Цепочка согласований (руководитель → бухгалтерия), 
бронь билетов и гостиницы через корпоративный сервис

---

Моя ситуация: Еду на конференцию в Питер на 3 дня

Результат:

С базовым описанием LLM может выбрать процедуру правильно, но не поймёт какие поля заполнять и в каком формате. С обогащённым описанием LLM:

1. Точно выберет Процедуру 3
2. Сформирует корректный запрос с нужными полями
3. Использует правильный формат дат
4. Укажет правильный тип цели ("конференция")
5. Запросит недостающие данные (бюджеты) вместо того чтобы их выдумать

Слабость LLM: Модель плохо работает с недоопределёнными структурами. Видит название параметра propagationPolicy — не понимает что туда писать. Встречает вложенную схему — путается в уровнях вложенности. Додумывает, ошибается.

Сильная сторона LLM: Модель отлично работает с примерами (few-shot learning). Показал один пример — схватила паттерн. Для формирования структурированных данных примеры работают как шаблон.

Механика метода:

• Описания снимают неоднозначность — модель понимает ЧТО делает параметр
• Constraints (допустимые значения) — модель видит границы
• Примеры — модель копирует формат и подставляет свои значения

Рычаги управления:

• Уровень детализации описаний — для простых задач достаточно краткого, для сложных нужно подробное
• Количество примеров — один пример для базового случая, несколько для разных сценариев
• Баланс краткость/детальность — краткое описание для выбора инструмента, детальное для корректного вызова

Выбери подходящую {действие/процедуру/опцию} и заполни нужные поля:

**{Название 1}**
Назначение: {Когда использовать, одним предложением}
Входные данные:
- {параметр_1} ({тип данных}, {constraint если есть})
- {параметр_2} ({тип данных}, {constraint если есть})
Пример: "{значение_1}, {значение_2}"
Результат: {Что получит пользователь}

**{Название 2}**
Назначение: {Когда использовать}
Входные данные:
- {параметр_1} ({тип}, {constraint})
- {параметр_2} ({тип}, {constraint})
Пример: "{значение_1}, {значение_2}"
Результат: {Что получит}

---

Моя ситуация: {описание задачи пользователя}

Что подставлять:

• {действие} — что выбираем: процедуру, сервис, тип анализа
• {Название} — понятное название опции
• {Назначение} — когда эту опцию использовать
• {параметр} — какие данные нужны
• {тип} — строка, число, дата, список
• {constraint} — ограничения: формат, допустимые значения, диапазон
• {Пример} — реальные значения для корректного заполнения
• {Результат} — что произойдёт после выбора

🚀 Быстрый старт — вставь в чат:

Помоги настроить описания для бота. У меня есть {количество} 
процедур/опций/действий: {перечисли их}. 

Создай для каждой структурированное описание по этому шаблону:

[вставить шаблон выше]

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

⚠️ Эффект зависит от размера модели: Маленькие модели (8B параметров) путаются при избыточной детализации — слишком много текста сбивает с толку. Средние (70B) показывают наилучший результат с полным обогащением. Большие (405B) иногда чрезмерно обобщают — видят пример с числом, но всё равно форматируют как строку.

⚠️ Не для всех задач: Обогащение помогает когда нужно выбрать из списка и заполнить структуру. Для свободного диалога или креатива избыточная структуризация ограничивает.

⚠️ Trade-off длина промпта: Детальные описания съедают токены. Для большого набора опций (50+) нужен механизм фильтрации — иначе не влезет в контекст.

Команда взяла два корпоративных API: Salesloft (42 метода, маркетинг и продажи) и Kubernetes (86 методов, управление контейнерами). Для каждого API сгенерировали реалистичные пользовательские запросы — всего около 300 задач.

Создали четыре варианта документации:

1. No Enrich — оригинал как есть
2. Enrich-1 — только описание метода
3. Enrich-2 — описание метода + описания параметров
4. Enrich-3 — всё из Enrich-2 + примеры параметров

Прогнали через три модели разного размера: Granite-8B (маленькая), Llama-70B (средняя), Llama-405B (большая). Измеряли:

• Выбрал ли агент правильный инструмент (selection accuracy)
• Сколько ошибок в параметрах — неправильный тип, пропущенные или выдуманные поля

Неожиданный результат: Большая модель (405B) НЕ всегда лучше с обогащённой документацией. Она начинает упрощать все типы до строк — видит {"count": 5} в примере, но генерирует {"count": "5"} как строку. Средняя модель (70B) показала наилучший баланс — использует детали правильно.

Второе открытие: Для shortlisting (выбор топ-k инструментов) обогащение критично при малых k. При топ-3 точность выросла на 10% по сравнению с базовым описанием. При топ-20 разница исчезла — релевантные инструменты попадают в выборку и так.

Практический инсайт: Если у тебя большой набор опций (20+), начни с краткого обогащения для фильтрации, затем дай детальное только для финалистов. Это экономит токены и улучшает точность.

Также протестировали на реальном продукте — IBM Watsonx Orchestrate. 46 инструментов, 600 запросов. Обогащение подняло точность вызова на 27% по сравнению с минимальной документацией и сравнялось с ручной разметкой разработчиков.

Automated Creation and Enrichment Framework for Improved Invocation of Enterprise APIs as Tools

Авторы: Prerna Agarwal, Himanshu Gupta, Soujanya Soni, Rohith Vallam, Renuka Sindhgatta, Sameep Mehta

Организация: IBM Research, India