Коротко: каталог операцій — це головне проєктне рішення MCP-інтеграції. Він визначає і що система вміє, і наскільки вона безпечна. Нижче приклади за чотирма напрямами, з яких можна відштовхуватися, складаючи свій.
Три правила складання каталогу
Операції за метою, а не за таблицями. Не «отримати записи книги клієнта», а «отримати прострочену заборгованість». Перше вимагає, щоб модель знала структуру бази; друге — щоб вона знала, чого хоче користувач. Друге надійніше й безпечніше.
Кожна операція повертає готове до використання. Якщо для відповіді потрібно поєднати три таблиці, це робить ваш код, а не модель через три виклики. Інакше агент упреться в обмеження інтенсивності запитів Business Central, а обсяг переданих назовні даних зросте втричі.
Опис важливіший за назву. Модель обирає операцію за описом. «Повертає прострочену заборгованість із розбивкою по клієнтах; не включає суми, позначені як спірні» — робочий опис. «Дебіторка» — ні.
Фінанси
| Операція | Параметри | Тип |
|---|---|---|
| Прострочена заборгованість | Мін. сума, днів, компанія | Читання |
| Платіжна поведінка клієнта | Клієнт, період | Читання |
| Рахунки до сплати за строками | Період, мін. сума | Читання |
| Знижки за дострокову оплату | Період | Читання |
| Обіг за категоріями ГК | Період, виміри | Читання |
| Розклад зміни маржі | Період, розріз | Читання |
| Позиції звірки без відповідності | Рахунок, період | Читання |
| Оновити дату контакту по боргу | Клієнт, дата | Запис |
Зверніть увагу на «розклад зміни маржі»: це не запит до таблиці, а розрахунок за вашим визначенням маржі. Саме такі операції й виправдовують власний сервер — стандартний конектор такого не дасть. Контекст — у статті про фінансового агента.
Продажі
| Операція | Параметри | Тип |
|---|---|---|
| Продажі за розрізом | Період, розріз, порівняння | Читання |
| Клієнти поза власним інтервалом | Множник інтервалу | Читання |
| Ціна для клієнта | Клієнт, номенклатура, кількість | Читання |
| Знижки понад політику | Період, продавець | Читання |
| Перевірка кредитних умов | Клієнт, сума | Читання |
| Зіставити назву з номенклатурою | Текст, клієнт | Читання |
| Створити замовлення в чернетці | Клієнт, рядки | Запис |
| Запам'ятати відповідність назви | Текст, клієнт, номенклатура | Запис |
Останні дві разом дають механізм, який покращується сам: агент зіставляє клієнтську назву позиції, менеджер виправляє помилку, пара запам'ятовується й наступного разу зіставлення точніше. Розгорнуто — у статті про агента для продажів.
Запаси
| Операція | Параметри | Тип |
|---|---|---|
| Покриття з урахуванням надходжень | Номенклатура, локація, горизонт | Читання |
| Фактичні терміни постачальника | Постачальник, категорія | Читання |
| Позиції під ризиком дефіциту | Локація, горизонт | Читання |
| Замовлення клієнтів під позицією | Номенклатура, період | Читання |
| Позиції без руху | Днів без руху, мін. вартість | Читання |
| Структура попиту за період | Номенклатура, період | Читання |
| Створити замовлення закупівлі | Постачальник, рядки | Запис |
«Структура попиту» тут не декоративна: вона дозволяє відрізнити регулярний попит від разового сплеску, через який механізм планування пропонує закупити зайве. Деталі — у статті про агента для запасів.
Довідники
Найпростіший каталог і найкращий для першого проєкту: ризик мінімальний, а користь видима.
- Знайти контрагента за назвою, кодом або реквізитами — з урахуванням різних написань.
- Знайти можливі дублікати за поєднанням ознак, а не за однією.
- Записи з незаповненими обов'язковими полями — параметр: тип довідника.
- Оновити конкретне поле — окрема операція на кожне поле, яке дозволено змінювати.
Останній пункт ілюструє головне правило: не одна операція «оновити картку», а окрема на кожне поле. Тоді перелік дозволеного читається як список, а не як припущення.
Чого в переліку не повинно бути
- Довільний запит. «Виконати запит», «отримати дані з таблиці X із фільтром» — переносить межу безпеки з коду в судження моделі.
- Загальне оновлення запису. Дозволяє змінити те, чого ви не мали на увазі, — кредитний ліміт разом із адресою.
- Проведення документів у фінансових сценаріях. Див. розбір операцій запису.
- Видалення. Майже завжди достатньо позначки, а видалення необоротне.
- Операції, що повертають цілі таблиці. Більше даних назовні й швидкий вихід на обмеження запитів.
Як писати описи, щоб модель обирала правильно
Каталог складено, операції написані, а агент усе одно поводиться дивно: викликає не те, плутає схожі операції, іноді ігнорує потрібну. Майже завжди причина в описах, і це та частина роботи, на яку йде найбільше часу при налагодженні.
Модель не бачить вашого коду. Вона обирає операцію за назвою, описом і схемою параметрів — тобто рівно за тим, що ви написали словами. Чотири правила, які знімають більшість проблем.
Пишіть, коли застосовувати, а не що робить операція. «Повертає прострочену заборгованість» описує реалізацію. «Використовуй, коли треба дізнатися, хто зі клієнтів не заплатив вчасно» описує ситуацію вибору — а вибір і робить модель.
Явно вказуйте, чого операція не робить. Якщо розрахунок не включає суми, позначені як спірні, це має бути в описі. Інакше модель упевнено подасть неповну цифру як повну, і помітите ви це нескоро.
Розводьте схожі операції в описах. Якщо у вас є «продажі за період» і «продажі за клієнтом», у кожному описі має бути сказано, чим саме вона відрізняється від сусідньої. Найчастіша причина неправильних викликів — дві операції, які за описом виглядають взаємозамінними.
Описуйте параметри так само ретельно. «Період» — погано. «Початок і кінець періоду; якщо не вказано, береться поточний місяць» — добре, бо знімає цілий клас запитань, коли модель починає вигадувати значення.
Практична перевірка: дайте каталог людині, яка не знає вашої системи, і попросіть обрати операцію під п'ять запитань. Якщо вона помиляється, помилятиметься й модель — і виправляти треба опис, а не промпт.
Скільки операцій потрібно
Практичний орієнтир: перша версія — вісім-п'ятнадцять операцій під один напрям. Менше зазвичай не покриває сценарій, більше означає, що ви намагаєтеся закрити все одразу.
Верхня межа не в кількості, а в читабельності: перелік має вміщатися в документ, який читається за один раз. Якщо його неможливо охопити поглядом, його ніхто не перевірить, а модель почне обирати гірше — при великому каталозі описи розмиваються й операції плутаються між собою.
Коли каталог розростається, правильний крок — не скорочувати, а розділяти сервери за напрямами: фінансовий окремо, складський окремо. Тоді кожен лишається перевірюваним.
Що зробите самі
Список операцій, які вам потрібні, ви складете краще за будь-кого: це знання про ваші процеси. Хороша вправа — виписати десять запитань, які у вас реально ставлять, і під кожним написати, з яких даних складається відповідь. Це вже майже каталог.
Складна частина — перекласти це в операції під модель даних Business Central: які саме таблиці, чим записи складу відрізняються від вартісних, як рахувати маржу за вашим визначенням. Тут потрібне знання системи, а не лише API.
Орієнтир: AI Discovery від $750 — саме на цьому етапі й складається каталог, і документ лишається вам. Асистент від $3 000, агент від $6 000.
Часті запитання
З чого починати складати каталог?
З десяти запитань, які у вас реально ставлять. Під кожним випишіть, з яких даних складається відповідь. Це майже готовий перелік операцій, і скласти його ви можете без підрядника.
Скільки операцій у першій версії?
Вісім-п'ятнадцять під один напрям. Менше зазвичай не покриває сценарій, більше означає спробу закрити все одразу — тестування розтягнеться, а модель почне плутати схожі операції.
Чи можна зробити одну універсальну операцію замість багатьох?
Технічно так, і саме цього не роблять. Універсальна операція переносить межу безпеки з вашого коду в судження моделі й віддає назовні більше даних, ніж потрібно.
Що робити, коли каталог розростається?
Розділяти сервери за напрямами: фінансовий окремо, складський окремо. Кожен лишається перевірюваним, а описи операцій не розмиваються.
Чи потрібні операції запису одразу?
Ні, і краще без них у першій версії. Асистент лише для читання дає більшу частину користі за мінімального ризику, а право запису додається після того, як стане ясно, що відповідям довіряють.
Наскільки детальними мають бути описи операцій?
Досить, щоб модель обрала правильно: що повертає, коли застосовувати, чого не включає. Формулювання на кшталт «дебіторка» призводить до викликів не вчасно, і це найчастіша причина дивної поведінки.