OpenAI function calling: як безпечно підключити ШІ до API

Що таке function calling простими словами

Звичайна модель відповідає текстом. Але статус замовлення, погоду чи баланс вона не знає без доступу до актуального джерела. Function calling дозволяє описати доступну дію — наприклад, get_order_status — і дати моделі її назву, призначення та JSON Schema аргументів.

Коли користувач запитує «Де моє замовлення 4821?», модель може повернути структурований виклик із order_id: "4821". Вона не запускає функцію. Код вашого застосунку отримує пропозицію, перевіряє її, викликає власну базу або API, а потім передає результат назад моделі. Лише після цього модель формує людську відповідь.

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

Як проходить один виклик

1. Застосунок надсилає запит. Разом із повідомленням він передає моделі лише потрібні цього разу інструменти.
2. Модель пропонує функцію. У відповіді з’являється елемент function_call з назвою, JSON-аргументами й унікальним call_id.
3. Сервер перевіряє межі. Назва входить в allowlist, аргументи валідні, користувач авторизований, дія дозволена.
4. Сервер виконує власний код. Ключі бази й зовнішніх API ніколи не передаються моделі.
5. Результат повертається моделі. Елемент function_call_output пов’язується з викликом через call_id.
6. Модель пояснює результат. Фінальна відповідь спирається на фактичні дані інструмента.

OpenAI Responses API може повернути нуль, один або кілька викликів. У першій версії інтеграції краще встановити parallel_tool_calls: false: тоді модель запропонує щонайбільше один інструмент за крок, а логіка перевірки й повторів буде простішою.

Function calling, Structured Outputs чи MCP

Не змушуйте function calling виконувати те, що достатньо сформувати як JSON. І навпаки: не приймайте JSON-текст від моделі за дозвіл змінити базу. Детальніше про стабільний фінальний формат читайте в гайді про Structured Outputs, а про стандарт інтеграцій — у поясненні що таке MCP.

Проєктуємо найменший безпечний інструмент

Для прикладу беремо лише читання статусу замовлення. Не додаємо refund_order, delete_order чи універсальний run_sql. Чим вужча функція, тим легше пояснити її моделі, перевірити права й написати тести.

const tools = [{
  type: "function",
  name: "get_order_status",
  description: "Повертає статус замовлення поточного користувача.",
  strict: true,
  parameters: {
    type: "object",
    additionalProperties: false,
    properties: {
      order_id: {
        type: "string",
        pattern: "^[0-9]{4,12}$",
        description: "Номер замовлення з 4–12 цифр."
      }
    },
    required: ["order_id"]
  }
}];

strict: true змушує аргументи відповідати підтримуваній схемі. Для strict-функцій кожен об’єкт має містити additionalProperties: false, а всі оголошені поля — входити в required. Якщо значення може бути відсутнім, його тип включає null.

Схема — перша межа, але не авторизація. Ми навмисно не просимо модель передати user_id: інакше вона могла б підставити чужий. Ідентифікатор користувача сервер бере з перевіреної сесії.

Повний приклад через Responses API

Встановіть SDK і передайте ключ через змінну середовища. Ключ OpenAI, доступ до бази та сесія користувача мають залишатися на сервері.

npm install openai
export OPENAI_API_KEY="ваш_ключ"

import OpenAI from "openai";
import { toResponseInputItems } from
  "openai/lib/responses/ResponseInputItems";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

// У production ці дані надходять із БД.
const orders = new Map([
  ["4821", { ownerId: "user_7", status: "paid", eta: "2026-10-03" }],
  ["7319", { ownerId: "user_9", status: "shipped", eta: "2026-10-02" }]
]);

const tools = [{
  type: "function",
  name: "get_order_status",
  description: "Повертає статус замовлення поточного користувача.",
  strict: true,
  parameters: {
    type: "object",
    additionalProperties: false,
    properties: {
      order_id: {
        type: "string",
        pattern: "^[0-9]{4,12}$"
      }
    },
    required: ["order_id"]
  }
}];

function getOrderStatus(args, authUserId) {
  if (!/^[0-9]{4,12}$/.test(args.order_id)) {
    return { ok: false, error: "invalid_order_id" };
  }

  const order = orders.get(args.order_id);
  if (!order || order.ownerId !== authUserId) {
    // Не повідомляємо, чи існує чуже замовлення.
    return { ok: false, error: "not_found" };
  }

  return { ok: true, status: order.status, eta: order.eta };
}

const authUserId = "user_7"; // У production — із перевіреної сесії.
const conversation = [{
  role: "user",
  content: "Який статус замовлення 4821?"
}];

let response = await client.responses.create({
  model: "gpt-6-astra",
  instructions: [
    "Допомагай лише зі статусом замовлення.",
    "Не вигадуй дані та не проси секрети.",
    "Відповідай українською."
  ].join(" "),
  input: conversation,
  tools,
  tool_choice: "auto",
  parallel_tool_calls: false
});

conversation.push(...toResponseInputItems(response.output));

for (const item of response.output) {
  if (item.type !== "function_call") continue;
  if (item.name !== "get_order_status") {
    throw new Error(`Заборонений інструмент: ${item.name}`);
  }

  let args;
  try {
    args = JSON.parse(item.arguments);
  } catch {
    args = { order_id: "" };
  }

  const result = getOrderStatus(args, authUserId);
  conversation.push({
    type: "function_call_output",
    call_id: item.call_id,
    output: JSON.stringify(result)
  });
}

response = await client.responses.create({
  model: "gpt-6-astra",
  instructions: "Поясни результат коротко українською.",
  input: conversation,
  tools,
  parallel_tool_calls: false
});

console.log(response.output_text);

Відповідь на кшталт «Замовлення 4821 оплачене, очікувана дата — 3 жовтня» з’являється лише після результату серверної функції. Якщо користувач user_7 попросить замовлення 7319, сервер поверне загальне not_found і не розкриє, що чужий запис існує.

Сім меж безпеки для реального продукту

1. Мінімальні повноваження. Давайте інструменту доступ лише до потрібної таблиці, операції й користувача. Для Supabase додатковою межею мають бути RLS-політики.
2. Короткий allowlist. Передавайте моделі тільки інструменти, доречні на поточному екрані чи етапі. Responses API також підтримує tool_choice для примусового або обмеженого вибору.
3. Серверна валідація. Перевіряйте тип, формат, довжину, діапазон, існування запису та бізнес-правила після JSON.parse.
4. Авторизація поза моделлю. Користувач, роль і організація беруться із сесії або перевіреного токена, а не з аргументів функції.
5. Людське підтвердження. Повернення коштів, видалення, публікація, надсилання листів і зміна доступів мають зупинятися перед побічним ефектом.
6. Ідемпотентність. Записувальні операції отримують унікальний ключ запиту, щоб мережевий retry не створив дві оплати чи два листи.
7. Безпечні журнали. Логуйте назву інструмента, результат перевірки й request ID, але не API keys, паролі, повні персональні дані або токени сесії.

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

Як перевірити інтеграцію перед запуском

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

Типові помилки

• Одна універсальна функція. execute_action(action, payload) приховує реальний рівень ризику. Краще кілька вузьких функцій із різними дозволами.
• Довіра до strict як до firewall. Схема контролює форму, а не право переглянути запис чи безпечність операції.
• User ID в аргументах моделі. Його треба брати з авторизованої сесії.
• Автоматичні записи одразу після виклику. Між пропозицією моделі й побічним ефектом потрібні перевірки, а для високого ризику — підтвердження.
• Усі інструменти в кожному запиті. Це збільшує вибір, складність і поверхню атаки. Передавайте потрібний піднабір.
• Секрети у фронтенді. Зберігайте OpenAI API key лише на сервері; якщо він витік, скористайтеся планом із гайда з безпеки ключів.

Чекліст перед production

• Кожна функція має одну зрозумілу мету й мінімальні повноваження.
• Увімкнено strict: true, additionalProperties: false, усі поля перелічені в required.
• Назва функції перевіряється через allowlist; немає eval або довільного SQL.
• Аргументи повторно валідовані сервером.
• Користувач і роль надходять із перевіреної сесії.
• Чутливі операції мають підтвердження, ліміти й idempotency key.
• Помилки не розкривають чужі записи, секрети або внутрішню структуру.
• Є тести на чужий ID, prompt injection, помилковий формат, retry і таймаут.
• Логи дозволяють розслідувати виклик без збереження секретів.

Короткі відповіді

Чи виконує OpenAI функцію замість сервера?

Ні. Модель лише формує назву й аргументи. Ваш код перевіряє запит, виконує дозволену функцію та повертає її результат через function_call_output.

Чи достатньо strict: true?

Ні. Strict стабілізує JSON-аргументи, але не перевіряє авторизацію, власника запису, ліміти й наслідки. Це відповідальність сервера та бази.

Коли потрібне підтвердження людини?

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

Чим function calling відрізняється від Structured Outputs?

Structured Outputs формує передбачувану фінальну відповідь. Function calling просить ваш застосунок виконати інструмент, отримати актуальний результат і повернути його моделі.