Агент настільки здібний, наскільки здібні інструменти, які він може викликати. Команди тижнями налаштовують системний промпт, а потім відкривають бекенд моделі як тридцять тонких обгорток над REST-ендпоінтами — і дивуються, чому агент обирає не той інструмент, передає некоректні ідентифікатори і тоне в JSON-відповідях на 50 кілобайт. Інструменти для агентів — це новий вид API, споживачем якого є мовна модель. Він потребує інших рішень, ніж API для програмістів. У гайді — ці рішення на основі рекомендацій вендорів, досліджень і того, що, за нашим досвідом, працює.

Чим інструменти агентів відрізняються від API

Розробник може годину розбиратися з документацією вашого API, один раз написати код і детерміновано викликати API мільйони разів. Модель читає визначення інструментів у кожному запиті, мусить миттєво вирішити, який інструмент викликати і з якими аргументами, і платить за кожен токен входу й виходу в обмеженому контекстному вікні.

Дослідження SWE-agent показало, що дизайн інтерфейсу агент–комп'ютер — які є команди, як форматується вивід, як повідомляються помилки — змінює продуктивність агента не менше, ніж вибір моделі (Yang et al., 2024). Інженерний гайд Anthropic про написання інструментів для агентів доходить того самого висновку з продакшен-досвіду: дизайн інструментів — один із найпотужніших важелів покращення.

Принцип 1: Проєктуйте під задачі, а не під ендпоінти

Відображення REST-ендпоінтів на інструменти один до одного — найпоширеніша помилка. Якщо для відповіді на «коли приїде моє замовлення?» потрібні get_customer, list_orders, get_order, get_shipment і get_carrier_status, агент мусить правильно зв'язати п'ять викликів, і кожен коштує затримки й контексту.

Натомість проєктуйте інструменти навколо того, що агенту треба досягти:

Інструменти «під ендпоінти» Інструмент «під задачу»
list_orders, get_order, get_shipment, get_tracking get_order_status(order_ref) повертає статус, товари, перевізника й очікувану дату
list_users, list_events, create_event schedule_meeting(attendees, duration, window) знаходить вільні слоти й бронює
read_logs(service, from, to) повертає все search_logs(service, query, time_range, max_results)

Інструменти «під задачу» об'єднують типові багатокрокові операції, зменшують кількість рішень, які має ухвалити модель, і тримають контекст чистим. Залиште невелику кількість низькорівневих інструментів для нетипових випадків.

Принцип 2: Назви й описи — це промпти

Модель обирає інструменти за їхніми назвами й описами. Пишіть їх так, ніби пояснюєте інструмент новому колезі:

{
  "name": "search_customer_tickets",
  "description": "Search support tickets for ONE customer. Use this when the user asks about their previous requests or a problem they reported before. Returns at most 10 tickets, newest first, each with id, subject, status and a 200-character summary. To read the full conversation of a ticket, call get_ticket_thread with its id. Does not search other customers' tickets.",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": {"type": "string", "description": "Internal customer id like CUS-48213. Get it from the session context, never ask the user for it."},
      "query": {"type": "string", "description": "Keywords in Ukrainian or English. Leave empty to list recent tickets."},
      "status": {"type": "string", "enum": ["open", "closed", "any"], "default": "any"}
    },
    "required": ["customer_id"]
  }
}

Добрі описи кажуть, коли використовувати інструмент, що він повертає, чого він не робить і як пов'язаний з іншими інструментами. Описи параметрів задають формати й джерела значень. Спільний префікс для пов'язаних інструментів (crm_search_contacts, crm_get_deal) допомагає, коли в агента багато інструментів з різних систем.

Принцип 3: Повертайте те, що потрібно агенту, а не все, що маєте

Вивід інструмента потрапляє прямо в контекст моделі. Сирий рядок БД із 60 колонками, внутрішніми UUID і вкладеними метаданими марнує токени й відволікає модель.

  • Повертайте поля з високим сигналом. Людські назви замість непрозорих ідентифікаторів, де можливо; ідентифікатори — лише коли вони потрібні агенту для наступних викликів.
  • Дайте опцію детальності (response_format: "concise" | "detailed"), щоб агент міг попросити більше за потреби.
  • Пагінуйте й обрізайте з чіткими сигналами: «Показано 10 з 248 результатів. Звузьте запит або запитайте сторінку 2».
  • Форматуйте для читання. Підходить і короткий структурований текст, і компактний JSON; послідовність важливіша за формат.
  • Обмежуйте розмір у коді. Інструмент, що зрідка може повернути 2 МБ, рано чи пізно зламає сесію.

Контекст — найдефіцитніший ресурс агента, як пояснено у статті про контекстну інженерію.

Принцип 4: Помилки мають підказувати, що робити

Коли інструмент падає, повідомлення про помилку — єдина підказка моделі для відновлення. Порівняйте:

  • Error 400 — агент повторить той самий виклик або здасться.
  • Invalid date "15.09.2026": use ISO format YYYY-MM-DD, e.g. 2026-09-15. — агент виправить аргумент і досягне успіху.
  • Customer CUS-482 not found. Customer ids have 5 digits after "CUS-"; use search_customers by name or email to find the right id. — агент точно знає наступний крок.

Повертайте помилки як результати інструмента, а не кидайте винятки, що завершують цикл. Розрізняйте помилки, які модель може виправити (погані аргументи), і ті, що не може (сервіс недоступний), і кажіть про це: «Сервіс білінгу недоступний. Скажи користувачу спробувати пізніше; не повторюй виклик».

Принцип 5: Аргументи мають бути складно передати неправильно

  • Використовуйте enum для закритих множин.
  • Приймайте природні формати, якщо їх дешево нормалізувати в коді (дати, телефони, суми з валютою чи без).
  • Уникайте параметрів, які модель мусить обчислювати: зсувів, Unix-часу, внутрішніх кодів. Нехай інструмент сам перекладає «останні 7 днів» чи людську назву.
  • Суворо валідуйте і пояснюйте помилки, як вище.
  • Вмикайте суворі режими схем, якщо провайдер їх підтримує, щоб аргументи завжди відповідали схемі; див. структурований вивід.

Принцип 6: Дозволи живуть в інструменті, а не в промпті

Модель рано чи пізно викличе інструмент не так, як ви задумували, — через непорозуміння або через prompt injection у прочитаному вмісті. Безпеку треба забезпечувати в коді інструмента:

  • Виконуйте кожен виклик з правами кінцевого користувача, які перевіряє бекенд.
  • Розділяйте інструменти читання й запису; давайте інструментам запису вузькі права й вимагайте підтвердження для дій з наслідками.
  • Ніколи не приймайте ідентичність від моделі. Беріть customer_id з автентифікованої сесії, а не з аргументів інструмента, коли він визначає видимість даних.
  • Обмежуйте частоту й логуйте кожен виклик з користувачем, аргументами й результатом.

Повна модель безпеки описана у статті безпека AI-агентів і prompt injection.

Принцип 7: Набір інструментів — малий і без перетинів

Кожен додатковий інструмент додає токени до кожного запиту і ще один варіант, який модель може сплутати. Інструменти, що перетинаються, — search_docs, find_documents і query_kb, — надійне джерело хибних виборів. Цільтеся в невеликий набір чітко розмежованих інструментів на агента; якщо їх потрібні десятки, розподіліть відповідальність між спеціалізованими агентами або завантажуйте визначення інструментів динамічно залежно від задачі. Деякі платформи підтримують пошук інструментів, коли модель знаходить рідко використовувані інструменти на вимогу, а не бачить усі визначення одразу.

Відкриття інструментів через MCP

Якщо кілька агентів, IDE чи чат-клієнтів потребують тих самих можливостей, реалізуйте інструменти один раз як сервер Model Context Protocol. MCP стандартизує виявлення й виклик інструментів, тож ті самі інструменти CRM чи ERP працюють у Claude, асистентах IDE і ваших власних агентах. Усі принципи вище при цьому діють — MCP є транспортом, а не дизайном. Наше бізнес-орієнтоване введення — у статті MCP для бізнесу, а приклад для ERP — у статті інтеграція AI з Odoo.

Тестування інструментів через evals

Якість інструментів вимірювана. Зберіть набір реалістичних задач, що потребують інструментів, запустіть агента й виміряйте:

Метрика Що показує
Частка успішних задач Загальна корисність
Правильний вибір інструмента Незрозумілі назви чи інструменти, що перетинаються
Частка помилок в аргументах Нечіткі схеми чи формати
Викликів на задачу Брак інструментів «під задачу», погані відповіді
Токенів на задачу Роздуті відповіді
Відновлення після помилок Якість повідомлень про помилки

Потім ітеруйте: читайте транскрипти невдач, змінюйте описи, відповіді чи межі інструментів і перезапускайте. Гайд Anthropic радить давати моделі аналізувати невдалі транскрипти й пропонувати покращення інструментів — напрочуд ефективний цикл. Загальна методика — у статті evals для LLM.

Чек-лист для кожного інструмента

  • Спроєктований навколо задачі, яку агент справді виконує
  • Назва конкретна; опис каже, коли використовувати, що повертає і чого не робить
  • Кожен параметр має опис із форматом і джерелом
  • Відповідь містить лише поля з високим сигналом, з лімітами розміру й пагінацією
  • Помилки пояснюють, що сталося і що робити далі
  • Дозволи забезпечуються в коді, ідентичність береться із сесії
  • Дії запису з важливими наслідками потребують підтвердження
  • Покритий задачами в evals; помилки вибору інструмента й аргументів відстежуються

FAQ

Скільки інструментів може обробити агент? Сучасні моделі справляються з десятками добре спроєктованих інструментів, але точність і вартість погіршуються зі зростанням набору. Починайте з малого й додавайте інструменти, коли evals показують потребу.

Інструменти мають повертати JSON чи текст? Працює і те, й інше. Обирайте те, що найлегше читати моделі, і будьте послідовні в межах набору.

Чи можна автоматично згенерувати інструменти з OpenAPI-специфікації? Як стартову точку — так. Потім об'єднайте ендпоінти в інструменти «під задачі», перепишіть описи й скоротіть відповіді — згенерована версія рідко буває достатньо доброю.

Як версіонувати інструменти? Як API: додавання безпечне, ламкі зміни потребують нової назви чи версії, а evals мають запускатися на кожну зміну.

Джерела

  1. Anthropic (2025). Writing effective tools for agents — with agents.
  2. Yang et al. (2024). SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering.
  3. Anthropic. Tool use with Claude.
  4. OpenAI. Function calling guide.
  5. Model Context Protocol.
  6. Patil et al. (2023). Gorilla: Large Language Model Connected with Massive APIs.