Tool use і function calling

Що таке tool use (function calling) і яку проблему воно розвʼязує?

LLM уміє лише генерувати текст на основі того, що бачила під час навчання: поточної дати, вашого баг-трекера чи стану CI вона не знає, а решту правдоподібно вигадує. Tool use дає моделі спосіб попросити зовнішній код зробити конкретну дію — сходити в API, прочитати файл, запустити тест — і повернути результат назад у діалог. Механізм такий: разом із запитом ви передаєте моделі перелік доступних інструментів, і замість тексту вона може згенерувати структурований запит «поклич ось цей інструмент з такими аргументами». Практичний наслідок для AQA: увесь агентний стек (Claude Code, MCP-сервери, чат-боти, що заводять заявки) стоїть саме на цьому циклі, тож розуміння tool use — це розуміння того, чому агент іноді застрягає чи вигадує неіснуючий метод замість виклику.

Чому назва «function calling» оманлива?

Бо звучить так, ніби модель сама запускає ваш код, а це не так. Модель нічого не виконує — ні ваших функцій, ні власних; єдине, що вона робить, — генерує токени. Коли їй дали список інструментів, вона може згенерувати запит «хочу викликати інструмент X з аргументами Y» — і на цьому її роль закінчується. Далі вирішує й виконує ваш код: чи запускати функцію взагалі, як її виконати, що повернути. Ця межа не косметична — саме тому за валідацію, дозволи й наслідки відповідає ваш код, а не «модель, яка сама вирішила». Сильна відповідь додасть уточнення: це точно для client tools, тобто ваших власних інструментів; окремим родом стоять server tools (web_search, web_fetch, code_execution, tool_search), які виконує провайдер на своїй інфраструктурі — ви отримуєте вже результат, не обробляючи виконання.

З чого складається опис інструмента?

З трьох частин: імʼя, опис і схема аргументів. Імʼя (name) — унікальний ідентифікатор, за яким ваш код розрізняє інструменти (create_bug, get_test_case). Опис (description) — текст природною мовою, що пояснює не лише що інструмент робить, а й коли його кликати; фактично це міні-промпт для моделі. Схема аргументів (input schema або parameters) — це JSON Schema: типи полів, які обовʼязкові (required), які значення допустимі (enum), опис кожного поля. Різні провайдери називають зовнішнє поле по-різному, але всередині це та сама JSON Schema.

Чому кажуть, що модель обирає інструмент за описом, а не за назвою?

Бо саме текст опису — головний сигнал, за яким модель вирішує, чи цей інструмент підходить під поточний запит користувача. Розмитий чи неповний опис призводить до того, що модель кличе інструмент не до речі або взагалі його ігнорує, — і зовні це виглядає як баг агента. На сучасних моделях опис має бути прескриптивним: не просто «заводить баг», а «виклич, коли користувач описав дефект і попросив його зафіксувати». Практичний наслідок: якщо агент «не бачить» потрібного інструмента, першими правлять не модель, а опис.

Опишіть цикл виклику інструмента крок за кроком.

Крок 1: у запиті до моделі їдуть системний промпт, історія повідомлень і перелік доступних інструментів. Крок 2: модель відповідає — або готовим текстом, або запитом на виклик інструмента; ознака другого — окремий статус завершення, наприклад stop_reason: "tool_use", і в тілі імʼя інструмента з аргументами. Крок 3: ваш код розбирає цей запит і запускає справжню функцію. Крок 4: її результат їде назад до моделі як tool_result із посиланням на id виклику. Крок 5: модель бачить результат і або дає фінальну відповідь (end_turn), або просить наступний інструмент — цикл крутиться, доки не завершиться. Ключове: цим циклом керує ваш код, а не модель.

Хто керує циклом і чому це важливо для безпеки?

Циклом керує ваш код — модель лише реагує на кожному кроці. Це важливо, бо ваш код стоїть між «модель попросила» і «дія сталася»: він валідує аргументи, перевіряє дозволи, вирішує, чи потрібне підтвердження людини перед небезпечною операцією. Тому інцидент «AI видалив прод» — це не про те, що модель сама вирішила видаляти, а про те, що інструменту з правом видалення дозволили виконуватися без перевірки. Для QA це означає, що обʼєкт перевірки — не лише вибір моделі, а й обгортка навколо інструмента: валідація, дозволи, ліміти.

Чому tool use API називають stateless і що це означає для вартості?

Бо сервер моделі не памʼятає попередніх кроків: щоб модель «бачила» історію, ви щоразу надсилаєте весь діалог цілком — включно з минулими викликами інструментів і їхніми результатами. Памʼять діалогу — це те, що передаєте ви, а не те, що зберігає модель. Наслідок: із кожним кроком циклу історія росте, а разом з нею — кількість вхідних токенів і вартість запиту. Тому довгі агентні цикли з великими tool_result (наприклад, увесь лог тесту) швидко роздувають контекст — це те, що варто тримати в голові, оцінюючи вартість автоматизації.

Як через механізм інструментів отримати структурований вивід (structured output)?

Structured output — це той самий tool use, повернутий іншим боком. Замість дії ви описуєте інструмент зі схемою потрібної структури (наприклад, поля title / severity / steps) і змушуєте модель його викликати — на виході дістаєте JSON за цією схемою. Типовий кейс для QA: розпарсити вільний баг-репорт у поля або згенерувати тест-кейси у формі, що одразу лягає в TMS. Але поки не ввімкнено строгий режим, схема лише скеровує модель, нічого не гарантуючи: у виводі трапляються значення поза enum, пропущені обовʼязкові поля, зламані типи.

Чи гарантує JSON-схема, що модель поверне валідні дані?

Ні — і на співбесіді відповідь «так» це червоний прапорець. Без строгого режиму схема лише орієнтує модель, а результат може виглядати як валідний JSON, але містити "Critical" замість очікуваного "critical", зайве поле чи відсутнє обовʼязкове. Строгий режим (strict: true) прибирає структурні порушення — тип, enum і обовʼязкові поля збігаються, бо генерацію обмежують схемою. Але навіть тоді валідуйте на своєму боці: схема стежить за формою, а не за змістом (значення в межах enum може бути неправильним по суті), плюс строгий режим підтримує лише підмножину JSON Schema.

Що робить строгий режим (strict mode) і що саме він гарантує?

Строгий режим обмежує генерацію моделі так, щоб вивід структурно відповідав схемі — це роблять через grammar-constrained sampling, коли модель фізично не може згенерувати токен, що ламає схему. Він гарантує форму: правильний тип поля, значення в межах enum, наявність обовʼязкових полів. Чого він не гарантує — семантику: модель може обрати правильний за форматом, але хибний по суті severity. Плюс обмеження: строгий режим покриває лише підмножину JSON Schema, тож не кожна схема в нього вкладається. Тому валідація на своєму боці (ajv, zod) лишається обовʼязковою.

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

Перший — модель покликала погано: попросила інструмент, якого не існує, дала аргументу чужий тип або лишила обовʼязкове поле порожнім. Проти цього працюють схема (строгий режим відсікає частину порушень) і валідація перед виконанням. Другий — реальна функція впала: API віддало 500, стався таймаут, ресурс не знайдено. Тут головне правило — не обривати цикл, а повернути помилку моделі як tool_result з ознакою is_error, щоб вона могла адаптуватися. Це дві різні площини: перша про контракт «модель проти схеми», друга про надійність вашої інтеграції.

Інструмент упав посеред роботи агента. Як правильно вчинити?

Не кидати виняток, що обірве цикл, а повернути помилку моделі як tool_result з is_error: true і текстом, що саме сталося. Тоді модель прочитає помилку й адаптується: спробує інші аргументи, обере інший підхід або чесно скаже користувачу, що не вдалося. Якщо ж код кине виняток і зупинить цикл, агент просто «замовкне» посеред роботи — і зовні це виглядає як зависання, хоча причина в обробці помилки. Додатково варто мати ліміт ітерацій, щоб модель не зациклилася на «кличу → падає → кличу знову».

Навіщо в агентному циклі ліміт ітерацій?

Бо модель може зациклитися: покликати інструмент, отримати помилку, покликати знову з тими самими аргументами — і так нескінченно. Без обмеження кількості кроків цикл крутитиметься вічно, палячи токени й гроші, а в CI ще й впираючись у таймаут джоби. Ліміт ітерацій — це запобіжник, який зупиняє агента після N кроків і дає керовано завершити («не впорався за N спроб»). Для QA це один з інваріантів, який варто перевіряти в агентних продуктах: що є стеля кроків і що система коректно поводиться, досягнувши її.

Чому аргументи інструмента — це недовірений вхід?

Бо аргументи генерує модель, а не ваш код, і на них впливає все, що потрапило в контекст — включно з текстом користувача чи навіть вмістом сторінки, яку модель прочитала. Тул, що виконує shell-команду або SQL прямо з аргументів моделі, — це готовий вектор інʼєкції: досить підсунути моделі шкідливий текст, і вона згенерує небезпечні аргументи. Тому валідувати їх треба так само параноїдально, як користувацький ввід: перевірка типів, allow-list, екранування, а для небезпечних операцій — підтвердження людини. Це прямий місток до тем безпеки й prompt injection.

Що таке паралельні виклики інструментів і коли вони доречні?

Це коли модель в одній відповіді просить кілька інструментів одразу — доречно, коли виклики незалежні. Приклад: «дай статус тесту A і тесту B» — два виклики get_test_case, які ваш код може виконати конкурентно й повернути результати разом. Межа: коли другий виклик не може стартувати без результату першого (спершу створити баг, потім прикріпити отриманий id до тесту), паралель неможлива — лишається послідовність. Тобто модель сама вирішує розпаралелити незалежні дії, але коректність залежностей — на вашому боці дизайну інструментів.

Модель перестала робити паралельні виклики. Це вона «порозумнішала»?

Найчастіше ні — це наслідок того, що ваш код розбив tool_result на кілька окремих повідомлень замість повернути їх однією порцією. Коли модель просить кілька інструментів разом, усі результати треба повернути в одному повідомленні, привʼязавши кожен до свого id. Якщо ж їх слати частинами, модель бачить, що формат ламається, і в наступних кроках «вчиться» переходити на послідовні виклики. Тобто це не про інтелект моделі, а про те, як ваш код зібрав відповідь — типова пастка «виглядає як розумний вибір, а насправді зіпсований формат».

Як ви тестували б чат-бота, що заводить заявки через інструменти?

Обʼєкт перевірки тут не лише текст відповіді, а й поведінка навколо інструментів. Перевіряю: чи модель кличе правильний інструмент на відповідний запит (і не кличе, коли не треба); чи коректно заповнює схему (обовʼязкові поля, значення в межах enum, правильні типи); як оброблено помилку інструмента (API впало — бот адаптувався чи завис); що буде за паралельних і послідовних викликів; і чи система стабільна при недетермінізмі (той самий запит → той самий вибір інструмента). Оскільки модель недетермінована, тут ідуть не жорсткі асерти на текст, а evals і LLM-as-judge — це місток до відповідних тем.

Де AQA стикається з tool use щодня, навіть не називаючи це так?

Практично скрізь в агентному стеку. Агент — це і є цикл інструментів, обгорнутий у план: Claude Code читає файли, запускає тести, редагує код через виклики Read, Bash, Edit. MCP (Model Context Protocol) — це стандартизований tool use: Playwright MCP віддає моделі дії браузера (клік, ввід, скріншот) як інструменти. Генерація тест-артефактів через структурований вивід — теж цей механізм. І якщо продукт, який ви тестуєте, сам використовує інструменти, function calling стає безпосереднім обʼєктом ваших перевірок.

«AI видалив прод» — модель сама вирішила це зробити?

Ні. Модель не виконує дій — вона лише згенерувала структурований запит «поклич інструмент видалення з такими аргументами». Реально видалив ваш код, який виконав цей запит без валідації, перевірки дозволів чи підтвердження людини. Тому корінь інциденту завжди в обгортці: небезпечному інструменту дозволили виконуватися автоматично, без запобіжників. Правильна архітектура тримає руйнівні операції за підтвердженням або звужує права інструмента — і саме це, а не «поведінку моделі», має перевіряти QA.

Три кейси, де tool use перестає бути абстракцією: читання трейсу виклику (що каже кожне повідомлення в обміні), правильна обробка помилки інструмента (повернути моделі, а не впасти) і те, що саме перевіряти в чат-боті з function calling. Скрізь — що дивитися і чому.

Кейс 1. Читаємо трейс виклику: що каже кожне повідомлення

Чат-бот заводить баги. Користувач пише баг-репорт вільним текстом, а нас цікавить не фінальна фраза бота, а весь обмін під капотом. Ось як виглядає повний трейс однієї заявки (спрощено, у стилі Anthropic Messages):

[
  { "role": "user", "content": "Кнопка Save не працює на мобільному, застосунок падає. Заведи баг." },
  { "role": "assistant", "stop_reason": "tool_use", "content": [
    { "type": "text", "text": "Заводжу дефект." },
    { "type": "tool_use", "id": "toolu_01", "name": "create_bug",
      "input": { "title": "Save не працює на мобільному, застосунок падає", "severity": "critical" } }
  ]},
  { "role": "user", "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01",
      "content": "{\"id\": \"BUG-4213\", \"url\": \"https://tracker/BUG-4213\"}" }
  ]},
  { "role": "assistant", "stop_reason": "end_turn", "content": [
    { "type": "text", "text": "Готово: BUG-4213 (critical)." }
  ]}
]

Що дивитися і чому:

• stop_reason: "tool_use" на другому повідомленні — це ознака, що модель попросила інструмент, а не дала фінальну відповідь. У тесті асерт іде не на текст «Заводжу дефект», а на блок tool_use: його name і input.
• input проти схеми. title заповнено, severity — у межах enum (critical), обовʼязкові поля на місці. Це те, що перевіряє тест схеми. Зверніть увагу: модель сама вивела severity: critical з фрази «застосунок падає», хоча користувач ступеня впливу не називав.
• tool_result привʼязаний до id. tool_use_id: "toolu_01" посилається на конкретний виклик — без правильного звʼязку модель не зрозуміє, на що це відповідь. У трейсі це перше, що звіряють, коли «модель ігнорує результат інструмента».
• Останнє повідомлення без tool_use — це end_turn, цикл завершено. Якби тут знову зʼявився tool_use, модель просила б наступний крок, і цикл крутився б далі.

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

Трекер лежить, API віддає 500. Різниця між «агент завис» і «агент упорався» — у тому, як ваш код обробив цю помилку.

// НЕПРАВИЛЬНО: виняток обриває цикл, і агент "замовкне"
async function runToolBad(name: string, input: unknown) {
  const res = await tracker.createBug(input); // кине, якщо 500
  return JSON.stringify(res);
}

// ПРАВИЛЬНО: помилку повертаємо моделі як tool_result з is_error
async function runTool(name: string, input: unknown) {
  try {
    const res = await tracker.createBug(input);
    return { content: JSON.stringify(res), is_error: false };
  } catch (e) {
    return { content: `Трекер недоступний: ${String(e)}`, is_error: true };
  }
}

Сам цикл — з лімітом ітерацій, щоб модель не крутилася вічно, і зі збором усіх результатів в одне повідомлення:

let messages = [{ role: "user", content: userInput }];
const MAX_STEPS = 10;

for (let step = 0; step < MAX_STEPS; step++) {
  const res = await model.create({ tools, messages });
  messages.push({ role: "assistant", content: res.content });
  if (res.stop_reason !== "tool_use") break; // фінальна відповідь

  const results = [];
  for (const call of res.content.filter((b) => b.type === "tool_use")) {
    const out = await runTool(call.name, call.input);
    results.push({
      type: "tool_result",
      tool_use_id: call.id,
      content: out.content,
      is_error: out.is_error,
    });
  }
  messages.push({ role: "user", content: results }); // усі результати однією порцією
}

Що дивитися і чому:

• is_error: true дає моделі шанс адаптуватися — повторити з іншими аргументами чи чесно сказати користувачу «трекер недоступний». Виняток такого шансу не лишає: цикл обірветься, і зовні це виглядатиме як зависання агента.
• MAX_STEPS — запобіжник від зациклення «кличу → падає → кличу знову». Без нього цикл крутиться, доки не впреться в таймаут CI й не спалить токени.
• Результати однією порцією. Усі tool_result ідуть у єдиному повідомленні. Розібʼєте на кілька — і модель поступово перестане робити паралельні виклики.

Кейс 3. Що саме перевіряти в чат-боті з інструментами

Коли продукт сам користується інструментами, обʼєкт перевірки — не текст відповіді, а вибір і аргументи інструмента. Ось карта перевірок:

Мінімальний тест дивиться на сам виклик, а не на фінальну фразу:

import { test, expect } from '@playwright/test';

test('на баг-репорт бот кличе create_bug з валідною схемою', async () => {
  const res = await agent.step('Save не працює на мобільному, застосунок падає. Заведи баг.');

  const call = res.content.find((b) => b.type === 'tool_use');
  expect(call, 'модель мала попросити інструмент, а не відповісти текстом').toBeTruthy();
  expect(call.name).toBe('create_bug');

  // схему перевіряємо, як перевіряли б відповідь чужого API
  expect(call.input.title).toBeTruthy();
  expect(['blocker', 'critical', 'major', 'minor']).toContain(call.input.severity);
});

Що дивитися і чому:

• Асерт на tool_use, а не на текст. У продукті з function calling обʼєкт перевірки — це вибір і аргументи інструмента, а не формулювання відповіді.
• Валідація схеми на своєму боці. Навіть якщо модель зазвичай віддає правильний enum, тест має ловити рідкісні зриви — бо в проді severity поза enum зламає інтеграцію з трекером.
• Один прогін недостатній. Через недетермінізм такий тест ганяють кілька разів або замінюють на eval-набір із порогом проходження — це вже територія evals і LLM-as-judge.

Суть механізму

• Розумію, що модель не виконує коду — лише генерує структурований запит на виклик; виконує й відповідає за наслідки мій код (тому назва «function calling» оманлива).
• Знаю межу цього твердження: воно точне для моїх інструментів (client tools), а server tools (web_search, web_fetch, code_execution, tool_search) виконує провайдер — частина дій відбувається поза моїм кодом, і модель загроз це враховує.
• Знаю, що циклом керує мій код, а не модель, і чому це основа безпеки (валідація, дозволи, підтвердження перед небезпечною дією).
• Можу пояснити, чому «AI видалив прод» — це про відсутність запобіжника в обгортці інструмента, а не про «рішення моделі».

Опис інструмента

• Знаю три частини опису: імʼя (name), опис природною мовою (description), схема аргументів (JSON Schema).
• Розумію, що модель обирає інструмент за описом, а не за назвою, тож опис має казати не лише «що робить», а й «коли кликати».
• Можу пояснити роль required і enum у схемі й що зовнішнє поле різні провайдери звуть по-різному (input_schema проти parameters), але всередині це та сама JSON Schema.

Цикл виклику

• Можу відтворити цикл: запит + інструменти → tool_use → виконання на моєму боці → tool_result за id → повтор до end_turn.
• Знаю, що ознака запиту на інструмент — окремий статус завершення (stop_reason: "tool_use").
• Розумію, що API stateless: історію я передаю щоразу цілком, і разом з нею ростуть токени й вартість.

Structured output і валідація

• Розумію, що структурований вивід — це той самий механізм інструментів, повернутий іншим боком.
• Можу пояснити, чому схема без строгого режиму — підказка, а не гарантія (значення поза enum, пропущене поле, зіпсований тип).
• Знаю, що дає строгий режим (форма: тип, enum, обовʼязкові поля) і чого не дає (семантику), що він покриває лише підмножину JSON Schema, тож результат усе одно валідують на своєму боці (ajv, zod), як відповідь чужого API.

Помилки і безпека

• Знаю два роди помилок: «модель покликала погано» (схема + валідація) і «реальна функція впала» (is_error).
• Можу пояснити, чому помилку інструмента повертають моделі як tool_result з is_error, а не кидають виняток, що обриває цикл.
• Розумію, навіщо ліміт ітерацій, і що без нього агент зациклюється й палить токени та гроші.
• Розумію, чому аргументи інструмента — недовірений вхід, і чому інструмент із shell/SQL з аргументів моделі — вектор інʼєкції.

Паралельні виклики

• Можу пояснити, коли доречні паралельні виклики (незалежні дії) і коли лише послідовні (результат першого — аргумент другого).
• Знаю, що всі tool_result треба повертати однією порцією, інакше «привчаєш» модель до послідовних викликів.

Де це в QA

• Розумію, що агент — це цикл інструментів у плані, а MCP — стандартизований tool use (Playwright MCP віддає дії браузера як інструменти).
• Можу назвати, що перевіряти в продукті з function calling: правильний інструмент, коректна схема, обробка помилок, паралельні/послідовні виклики, недетермінізм.