Найкращі практики виклику інструментів агентом: чому ваш агент обирає хибний інструмент

Найкращі практики виклику інструментів агентом: чому ваш агент обирає хибний інструмент

Найкращі практики виклику інструментів агентом — це те, що стоїть між робочою демоверсією та агентом, який у продакшені тихо викликає не той інструмент. Інженерна команда Anthropic виміряла, як один переписаний опис скоротив результат інструмента з 206 токенів до 72, а Claude Code тепер жорстко обмежує кожну відповідь інструмента на рівні 25 000 токенів, бо витік цілком реальний. Ваш агент помиляється чотирма способами: хибний інструмент, хибні аргументи, неконтрольований цикл, витік токенів. І на кожен є виправлення, яке можна викотити цього тижня.

Головні висновки:

• Виклик інструментів агентом дає збій рівно чотирма способами: хибний інструмент, хибні аргументи, неконтрольовані цикли та витік токенів.
• Описи інструментів є єдиною інструкцією, яку модель бачить у момент вибору, тож саме вони виправляють більшість хибних викликів.
• Плоскі схеми під форму задачі з валідованими входами усувають більшість збоїв на аргументах.
• Стислі відповіді інструментів і eval-цикл на кожну зміну тримають вартість токенів і регресії у вимірюваних межах.

Чому виклик інструментів агентом дає збій у продакшені?

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

Повний рецепт одним поглядом:

Опрацюйте їх саме в цьому порядку. Практики 1 і 2 займають один післяобідній час і прибирають більшість збоїв із хибним інструментом та хибними аргументами, які ви бачите сьогодні. Опис інструмента — це не документація. Це єдина інструкція, яку модель отримує в момент вибору.

Фаза 1: Проєктуйте інструменти, які модель справді може використовувати

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

Практика 1: Пишіть описи, за якими модель може діяти

Пишіть описи інструментів як інструкції для моделі, а не як API-документацію. Опис, який задовольняє розробника-людину («REST-обгортка для ендпоінта users»), не дає моделі жодної основи для рішення. Інженерний посібник Anthropic з написання інструментів та їхні найкращі практики визначень інструментів просувають один і той самий шаблон: скажіть, коли використовувати інструмент, що він повертає і коли НЕ використовувати його.

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

проти версії, яку відвантажує більшість команд:

{
  "name": "get_user",
  "description": "Gets a user."
}

Два правила виконують тут більшу частину роботи. Перше: називайте параметри так, щоб їхнє значення було однозначним: user_id, ніколи user чи id, бо user запрошує модель передати ім'я або email там, де має бути UUID. Друге: явно прописуйте винятки. Рядок «Do NOT use to search users» запобігає більшій кількості хибних викликів, ніж будь-який обсяг позитивного опису, бо моделі плутають інструменти, що перетинаються, набагато частіше, ніж неправильно розуміють один чітко окреслений інструмент. Про те, як ці визначення доходять до API OpenAI, Anthropic і Google на рівні провайдерів, читайте у нашому посібнику з function calling для кількох провайдерів.

Практика 2: Тримайте схеми плоскими й під задачу

Тримайте вхідні схеми плоскими, з усіма полями, яких справді потребує задача, і без жодного зайвого. Вкладені об'єкти з необов'язковими гілками стають розплідником збоїв на аргументах: модель мусить виводити структуру, прикладів якої ніколи не бачила. Посібник OpenAI з function calling приймає довільний JSON Schema, але дозвільний не означає надійний.

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Спростіть її під задачу:

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

Переліки (enum) кращі за довільний текст для будь-якого поля з обмеженим набором значень. Масиви required кращі за «все необов'язкове». Якщо модель майже завжди потребує певного поля, зробіть його обов'язковим у схемі інструмента, навіть коли ваш API називає його необов'язковим. Ви не дзеркалите свій API. Ви проєктуєте поверхню, яку одна конкретна модель може заповнити правильно.

Фаза 2: Керуйте набором інструментів, а не лише інструментами

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

Практика 3: Загортайте багатокрокові послідовності API в атомарні інструменти

Згортайте будь-яку фіксовану послідовність викликів API в один атомарний інструмент. Інженерна стаття Anthropic наводить schedule_event і get_customer_context як зразок: один виклик, що робить усю справу, кращий за три виклики, які агент мусить щоразу правильно зчеплювати. Кожна ланка в ланцюзі стає ще одним ходом, де модель може застрягти, хибно повторити спробу чи зациклитися.

# What the agent does WITHOUT an atomic tool: 3 calls, 3 chances to fail
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# One atomic tool: the sequence lives in your code, not the model's head
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

Емпіричне правило: якщо модель завжди мусить викликати B після A, то A і B — це один інструмент у двох костюмах.

Практика 4: Простори назв, скорочення та динамічна фільтрація інструментів

Давайте простір назв кожній назві інструмента і показуйте кожному агенту лише ту підмножину, якої потребує його поточна задача. Загальні назви стикаються тієї миті, як ви підключаєте дві інтеграції. Уявіть агента, підключеного до двох MCP-серверів, які обидва експонують інструмент під назвою search: два однакові дієслова, і жодного способу їх розрізнити. Anthropic документує вимірюваний приріст на евалах від префіксних просторів назв:

Скорочення важить не менше за назви. Агенту підтримки не потрібні його інструменти білінгу, завантажені, поки він відповідає на запитання про пароль. Патерн «планувальник-виконавець», де планувальник скеровує задачу виконавцю, який завантажує лише доречні інструменти, є стандартним виправленням; гайд LangGraph з динамічного завантаження інструментів розбирає реалізацію. Коли інструментів стає забагато? Трактуйте 5–10 на агента як робочий діапазон, а не закон: точність падає зі зростанням списку, і ліки тут не більша модель, а фільтрація. Якщо ви обираєте сам шар маршрутизації та фільтрації, порівняйте варіанти в нашому огляді найкращих бібліотек для function calling.

Фаза 3: Контролюйте, що повертається і що виходить

Цикл працює в обидва боки, а більшість команд інженерно опрацьовує лише вихідну половину. Те, що повертають ваші інструменти, визначає, яка частина вікна контексту доживе до наступного ходу, а те, що відхиляє ваша валідація, визначає, чи модель навчається на помилках, чи повторює їх.

Практика 5: Повертайте стислі, інформативні результати

Повертайте найменший результат, з яким модель може діяти, з людиночитними ідентифікаторами замість сирих ID. Інженерна стаття Anthropic документує інструмент, чий результат за замовчуванням сягав 206 токенів; стисле налаштування response_format скоротило той самий результат до 72 токенів, приблизно до третини обсягу. Помножте це на десятки викликів на задачу, і саме це вирішує, чи ваш агент узагалі завершить роботу.

// Before: 206 tokens (shape per Anthropic's documented example)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// After: 72 tokens
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

Ще дві деталі з того самого джерела: Anthropic підтримує enum response_format (detailed проти concise) у визначеннях інструментів, тож ви можете декларувати бажану форму, а не розбирати потік. А Claude Code обмежує відповіді інструментів на рівні 25 000 токенів, і це жорсткова стеля, яка однаково обрізає роздуті результати. Anthropic також повідомляє, як власний висновок, що розв'язання UUID у семантичні назви вимірювано зменшило галюцинації під час вибірки, і саме тому «після»-варіант вище каже «Dana Kim», а не c9a1...f2. Роздуті відповіді створюють і проблему вартості; повну картину дивіться в нашому посібнику зі скорочення витрат на LLM API.

Практика 6: Валідуйте кожен виклик і зробіть помилки навчальними

Валідуйте кожен виклик інструмента на боці сервера і повертайте помилки, що містять спосіб виправлення. Стаття Мартіна Фаулера про function calling формулює це прямо: ніколи не довіряйте виводу моделі. Вона передасть рядки там, де мають бути enum, і вигадає ID, яких не існує.

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

Рядок помилки — це вся гра. Порівняйте:

# Unhelpful: the model retries the same bad call
{"error": "invalid input"}

# Helpful: the model knows exactly what to change
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

Кожна помилка валідації, яку повертає ваш інструмент, стає промптом, який ви пишете для наступної спроби моделі. Помилки, що називають обмеження і вказують на інструмент для виправлення, перетворюють цикл повторних спроб на однокрокове відновлення. Це ще й ваша перша лінія безпеки; наш посібник із гардрейлів LLM розбирає це детально.

Фаза 4: Як зробити безпечно, а потім вимірювано?

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

Практика 7: Ставте руйнівні дії за підтвердження людини

Відокремте інструменти читання від інструментів запису і поставте шлюз підтвердження людиною на все руйнівне. Анотації інструментів у специфікації MCP існують саме для цього: destructiveHint позначає інструменти, що виконують руйнівні оновлення, а openWorldHint флагить інструменти, які чіпають зовнішні системи, тож клієнти можуть запитати перед виконанням. Використовуйте їх.

Режим збою тут не гіпотетичний. Лоран Кубаскі задокументував випадок у своїй статті про виклик інструментів за липень 2025 року з посиланням на оригінальний звіт: користувач попросив Copilot в Excel опрацювати рядок 4, а агент натомість спрацював на рядку 8. Жодного шлюзу підтвердження між хибним рядком і записом не стояло. Виправленням слугує патерн, який AWS документує для Bedrock Agents: агент готує дію, повертає її на затвердження і виконує лише після підтвердження людиною. Cursor робить те саме для редагувань файлів. Обмежуйте облікові дані до режиму лише-читання, коли задачі достатньо лише читання, і трактуйте шлюзи підтвердження як частину вашої поверхні ін'єкцій, теми нашого посібника із запобігання prompt injection.

Практика 8: Запускайте eval-цикл на кожну зміну інструмента

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

Кулінарна книга Anthropic з оцінювання інструментів, побудована на реальних евалах Slack і Asana MCP, показує, як виглядають добрі та слабкі оцінювальні задачі:

# Weak: vague, many valid paths, impossible to score
"Use the Asana tools to organize some work."

# Strong: one correct tool, checkable arguments, binary outcome
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

Наша інтерпретація, позначена як така: опубліковані цифри дають вам порядок роботи. Перевіряйте коректність інструмента першою, бо власні вимірювання Anthropic показують, що зміни описів і назв рухають її напряму (перепис із 206 до 72 токенів, висновок про галюцинації UUID-у-назву), а ефективність задачі залиште наостанок, оскільки вона здебільшого відбиває збої, які перші три метрики вже спіймали. Для стартового набору спроєктуйте 15–30 задач, по дві-три на інструмент, кожна з одним очікуваним викликом і бінарною умовою проходження. Такого розміру достатньо, щоб спіймати регресію від перепису опису без тижня розмічання, і ми читаємо налаштування Slack і Asana з кулінарної книги як доказ, що такий невеликий набір є задуманою стартовою точкою, а не скороченням. Глибша механіка живе в нашому посібнику з оцінювання AI-агентів у продакшені, і якщо результати евалів кажуть, що самі інструменти в порядку, а оркестрація ні, тоді час передивитися вибір фреймворку порівняно з найкращими фреймворками для AI-агентів.

Виклик інструментів агентом проти MCP: у чому різниця?

MCP — це стандарт транспорту та реєстру, а не шар надійності, тож ті самі вісім практик застосовуються незалежно від того, чи ваші інструменти приходять через MCP, чи визначені інлайн. Нативний виклик інструментів є контрактом між моделлю та провайдером: як модель випускає tool_call і читає tool_result. MCP стандартизує, як інструменти доходять до моделі; він нічого не робить із тим, чи модель обирає правильний.

MCP-сервер, який експонує інструмент під назвою search з описом «шукає речі», ламається ідентично інлайн-функції, визначеній так само. Виправте визначення, тоді переймайтеся транспортом. Наш посібник із Model Context Protocol покриває протокольну сторону від початку до кінця.

Як Techsy застосовує ці вісім практик

На кожній збірці клієнтського агента ми впроваджуємо три з них ще до того, як щось інше піде в реліз: описи, написані як інструкції (практика 1), шлюзи валідації на кожному інструменті запису (практика 6) і eval-набір, який запускається до деплою, а не після інциденту (практика 8). Ці три покривають виклики хибного інструмента, виклики з хибними аргументами та регресії, що повертають обидва, а саме звідси починався кожен інцидент продакшен-агента, який ми діагностували. Решта п'яти практик іде слідом, коли агент росте. Якщо ваш агент минув стадію демо і обирає хибні інструменти, отримайте безкоштовну консультацію, і ми скажемо, яку з восьми виправляти першою.

Про автора

Мерт Батур є співзасновником Techsy.io, де команда відвантажує AI-агентів, системи автоматизації та голосові/SDR-конвеєри для B2B-клієнтів. Він пише про стек LLM-інструментарію, який команда Techsy справді використовує в продакшені. Підключайтеся в LinkedIn.

Часті запитання

Що таке виклик інструментів агентом?

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

Як працює цикл виклику інструментів агентом?

Цикл має п'ять кроків: запит користувача доходить до моделі, модель обирає інструмент і пише tool_call, ваш виконавець запускає його, tool_result повертається до моделі, і модель або відповідає, або робить ще один виклик. Цей цикл повторюється, доки задачу не завершено. Чотири режими збоїв у цьому посібнику кожен живе на конкретному кроці цього циклу.

Чому мій агент обирає хибний інструмент?

Зазвичай тому, що два інструменти перетинаються, а їхні описи не кажуть, який є який. Модель обирає лише на основі назв і описів, тож «gets a user» проти «finds users» читається як взаємозамінне. Виправте це рядками винятків («do NOT use to search»), назвами з простором назв і меншою кількістю інструментів у контексті. Тест Кубаскі на чотирьох моделях показав, що навіть сильні моделі хибно маршрутять на неоднозначних списках.

Як змусити агента з викликом інструментів структурувати вивід?

Обмежуйте схему, а не промпт. Використовуйте enum для обмежених полів, масиви required для всього, чого потребує задача, і плоскі об'єкти замість вкладених. Для фінальної відповіді, а не виклику інструмента, функції провайдерів на кшталт структурованого виводу OpenAI та режимів tool-choice Anthropic примусово задають конкретну форму. Наш посібник зі структурованого виводу покриває обидва шляхи з кодом.

Виклик інструментів агентом проти MCP: у чому різниця?

Нативний виклик інструментів є контрактом між вашим кодом і одним провайдером моделі: формат повідомлень tool_call і tool_result. MCP — це протокольний шар, який стандартизує, як інструменти виявляються і доставляються будь-якому сумісному клієнту. MCP змінює сантехніку, а не надійність. Погано описаний інструмент ламається однаково обома шляхами, як пояснює наш посібник із Model Context Protocol.

Коли інструментів для LLM-агента стає забагато?

Трактуйте 5–10 інструментів на агента як робочий діапазон, а не закон. Точність вибору падає зі зростанням видимого списку, особливо коли назви чи описи перетинаються. Ліки не в більшій моделі, а у фільтрації: завантажуйте лише підмножину, якої потребує поточна задача, використовуючи розподіл «планувальник-виконавець». Давайте простір назв усьому, щоб дві інтеграції ніколи не експонували обидві голий search.

Яка модель найкраща для виклику інструментів?

Єдиної відповіді немає, а опубліковані бенчмарки швидко старіють у цій сфері. Фронтирні моделі від OpenAI, Anthropic і Google усі проходять базові задачі з використанням інструментів, тоді як менші моделі в парі з добре спроєктованими інструментами часто завершують задачі майже так само часто за частку вартості токенів. Зберіть eval-набір на 15–30 задач із практики 8 і тестуйте кандидатів на власних інструментах.

Як зменшити вартість токенів від виклику інструментів?

Скорочуйте те, що повертається. Повертайте стислі, інформативні результати замість сирих API-пайлоадів: Anthropic задокументував скорочення з 206 до 72 токенів від однієї зміни response_format. Розв'язуйте UUID у назви, викидайте поля, які модель ніколи не використовує, і пам'ятайте, що кожен результат інструмента повторно входить у вікно контексту на кожному наступному ході. Менше викликів через атомарні інструменти прибирає цілі результати з рахунку.

Як оцінити якість виклику інструментів?

Оцінюйте чотири метрики за порядком: коректність інструмента (правильний інструмент?), точність вводу (валідні аргументи?), завершення задачі (досягнута мета?) та ефективність задачі (кількість токенів і викликів?). Напишіть 15–30 задач, кожна очікує один конкретний виклик з перевірюваними аргументами та бінарною умовою проходження. Запускайте набір до і після кожної зміни інструмента, щоб перепис опису ніколи не відвантажувався без вимірювання.

Висновок

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