Нікіта СавченкоНікіта Савченко всюди

Як я вбудував ШІ-агента в сервіс рахунків Jinna

18 лют. 2026 р.#tech #tutorial
262
English
Як я вбудував ШІ-агента в сервіс рахунків Jinna

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

Нещодавно я вбудував ШІ-агента в Jinna — безкоштовний сервіс, де виставляють рахунки. До речі, ви можете увійти й створювати там гарні✨ рахунки безкоштовно!

Це схоже на магію:

  • Просите ШІ-агента виставити рахунок — і він його створює.
  • Розуміє складні запити.
  • Розбирається з неоднозначностями.
  • Виконує ланцюжок змін і, якщо треба, дещо перепитує.

Нижче я ділюся тим, що знаю, щоб ви могли зробити схожого ШІ-агента для свого SaaS, продукту чи застосунку.

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

Що ви дізнаєтеся:

  • Як зрозуміти, чи потрібен вашому продукту ШІ-агент
  • Як по-справжньому використовувати LLM у продукті (а не лише для чату)
  • Як змусити LLM виконувати дії, а не тільки говорити
  • Цикл ReAct — основний патерн, на якому тримаються ШІ-агенти
  • Системні промпти, інструменти й керування контекстом
  • Практичні поради з досвіду запуску в продакшн

Порада: на етапі планування дайте цю статтю Claude Code чи іншому агентові для програмування, яким користуєтеся, — він допоможе все продумати й правильно збудувати! Так працює підхід «спершу план», який я описав у статті «Як бути розробником в епоху ШІ».

Чи потрібен вашому продукту текстовий ШІ-асистент?

Рано чи пізно люди зрозуміють: доручити будь-яку роботу ШІ-агентам зручніше й ефективніше, ніж користуватися звичними вебінтерфейсами різних продуктів.

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

У 2026 році починається перехід від «традиційних» інтерфейсів до таких, що їх доповнюють ШІ-агенти: вони не лише консультують, а й справді виконують завдання. Кожному вебзастосунку варто подумати про власного агента — в одній із цих форм:

  1. ШІ-агент у чаті поряд із «традиційним» інтерфейсом — найуніверсальніший варіант. Потребує певної інженерної роботи з вашого боку, зате гарантує однаковий результат для всіх клієнтів.
  2. Відкритий API з документацією або MCP-сервер — інші ШІ-агенти користуються вашим API і працюють із сервісом напряму, без «рідного» чат-агента. Чужий агент стає споживачем сервісу так само, як люди.

У кожного підходу є плюси і мінуси:

ПараметрАгент у чатіAPI / MCP-сервер
Досвід користувачаРозмовний формат, легко освоїтиЗалежить від агента-споживача, а в декого з користувачів навіть немає особистого ШІ-агента
Зусилля на розробкуБільші — інтерфейс чату + логіка агента + інструментиМенші — задокументуйте API і випускайте. Найімовірніше, ви це вже зробили.
Контроль над UXПовний — взаємодію проєктуєте виМінімальний — ваш API інтерпретують інші агенти
Неоднозначні запитиМоже ставити уточнювальні запитанняЗалежить від ШІ-агента-споживача. Контракти API жорсткі
ОхопленняЛише ваші користувачі-люди *Вашим сервісом може користуватися будь-який ШІ-агент

* Чат вашого агента можна відкрити іншим агентам як окрему можливість — схоже на те, що Google описує у своєму протоколі Agent2Agent (A2A).

Чим ШІ-агент відрізняється від чат-бота?

Різниця проста: чат-боти відповідають, агенти діють.

Схема архітектури: ШІ-агент і чат-бот

Чат-бот отримує повідомлення та повертає відповідь. Агент отримує повідомлення, думає, що робити, діє через інструменти, дивиться на результат і повторює все це, доки не виконає завдання.

Різниця в псевдокоді:

1// Chatbot
2function chatbot(message) {
3 return llm.generate(message);
4}
5
6// Agent
7function agent(message, context) {
8 while (!done) {
9 const thought = llm.think(message, context); // any capable LLM
10 if (thought.needsTool) {
11 const result = executeTool(thought.tool);
12 context.add(result);
13 } else {
14 return thought.response;
15 }
16 }
17}

Агенти користуються так званими «інструментами» (tools), ухвалюють рішення і пам'ятають контекст. Вони крутяться в циклі, доки не переконають себе, що впоралися з початковим запитом чи запитанням. Такий агент — радше колега, ніж розумний пошуковий рядок.

Інструменти тут — це заздалегідь запрограмовані дії з документацією. Інакше кажучи, це перелік умінь, які ви даєте своєму ШІ-агентові, наприклад:

  • Переглядати, створювати, редагувати й видаляти об'єкти та сутності вашої системи
  • Просити користувача щось увести.
  • Викликати ендпоінт API.
  • Усе що завгодно!

Будь-що! Спираючись на документацію, ШІ-агент сам вирішує, який інструмент узяти, залежно від того, що є в його «контексті» (про це далі).

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

Архітектура: огляд системи

Мозок складається із шести основних компонентів:

  1. Провайдер LLM — «рушій міркувань». Його легко замінити: Gemini, Claude, OpenAI, що завгодно.
  2. Системний промпт — «характер і правила». Пояснює моделі, хто вона така і як має поводитися.
  3. Реєстр інструментів — «руки». Функції, які агент може викликати, щоб справді щось робити.
  4. Цикл ReAct — цикл «подумай — зроби — подивись». Основний патерн виконання.
  5. Керування контекстом — «пам'ять». Що агент пам'ятає про розмову.
  6. Стрічка повідомлень — «журнал розмови». Що бачить користувач.

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

LLM (власне виклик API моделі) — ядро міркувань у цій системі: вона отримує вхідні дані й ухвалює рішення. Системний промпт — це виховання і навчання агента: він формує, як думає LLM, і дає їй самоусвідомлення. Інструменти — моторна кора: вони перетворюють рішення на дії. Контекст — пам'ять: усе важливе з минулого чи з поточної розмови (скажімо, яку вебсторінку зараз відкрито). Контекстне вікно — скільки LLM може охопити й «запам'ятати», перш ніж здатися та видати остаточне рішення. А цикл ReAct — свідоме мислення: ітеративний процес, у якому модель крок за кроком розв'язує задачу.

Коли каркас системи готовий, починається справжня людська (розробницька) робота: Мозок треба налаштувати. Але про все по черзі — почнімо із самого Мозку.

Вибір Мозку, або яку LLM-модель узяти

LLM можна замінити: та сама архітектура працює з Gemini, Claude, OpenAI чи будь-яким іншим провайдером. Але від вибору моделі залежать UX і вартість.

Я користувався Gemini Flash і Pro, і різниця між ними суттєва:

ПараметрGemini FlashGemini Pro
ШвидкістьШвидкаПовільніша
ВартістьДешевшаДорожча
Прості задачіДобре дає радуЗ гармати по горобцях
Неоднозначні запитиМоже вгадати й виконатиЧастіше перепитує
Складні міркуванняБуває, що «поспішає»Обмірковує задачу
Загальна оцінка ⭐️Буває ненадійноюЧудова, але повільніша

Порівняння Gemini Flash і Gemini Pro

Справжню різницю видно в крайніх випадках. Flash схильна виконувати те, що, як їй здається, ви маєте на увазі, а якщо задача надто складна — опускає руки. Pro частіше перепитує, коли не певна, обробляє більше контексту й розбирається з неоднозначністю на кілька рівнів глибше. Жодна з них не права на всі сто: Flash іноді вгадує правильно й заощаджує час, а Pro іноді перемудровує або все одно пропускає деталі, що лежать на поверхні.

Практичні поради:

  • Для прототипу починайте з Flash — швидкі ітерації, низька вартість
  • Перевіряйте крайні випадки на Pro, щоб побачити, що ви пропускаєте
  • Можна брати Flash для простих операцій читання, а Pro — для запису та складної логіки
  • Або: за замовчуванням працювати на Flash, а для багатокрокових задач перемикатися на Pro

Цикл ReAct: як думає Мозок

ReAct означає «Reason + Act» — «міркуй і дій». Саме на цьому патерні тримається робота агентів.

Цикл:

  1. Аналіз — оцінити запит користувача й поточний контекст
  2. Рішення — визначити, чи потрібен інструмент, чи можна відповісти одразу
  3. Виконання — якщо інструмент потрібен, викликати його
  4. Спостереження — подивитися, що вийшло
  5. Повтор або відповідь — або продовжити (з новою інформацією), або повернути остаточну відповідь

Реальний приклад. Користувач пише: «Створи новий рахунок для Acme»

Ітерація 1 — пошук:

  • Аналіз: користувач хоче рахунок для «Acme», але конкретних даних клієнта немає
  • Рішення: пошукати потрібного серед наявних клієнтів
  • Виконання: searchCustomers({ query: "Acme" })
  • Спостереження: 2 збіги — «Acme Corp» (acme@corp.com) і «Acme Studios» (hello@acmestudios.io)

Ітерація 2 — уточнення:

  • Аналіз: неоднозначно — підходять два клієнти
  • Рішення: треба запитати, який саме
  • Відповідь: «Під „Acme“ підходять два клієнти: Acme Corp (acme@corp.com) і Acme Studios (hello@acmestudios.io). Котрий із них?»
  • Користувач відповідає: «Acme Corp»

Ітерація 3 — створення рахунку:

  • Аналіз: користувач підтвердив Acme Corp, усі дані вже є після пошуку
  • Рішення: створити рахунок
  • Виконання: createInvoice({ clientName: "Acme Corp", clientEmail: "acme@corp.com" })
  • Спостереження: рахунок INV-456 створено

Ітерація 4 — відповідь:

  • Відповідь: «Готово! Створено чернетку рахунку INV-456 для Acme Corp. Додати позиції?»

Цей приклад показує три ключові вміння агента: знайти дані, перепитати користувача та виконати дію.

Спрощена реалізація на Node.js:

1async function reactLoop(userMessage, maxIterations = 10) {
2 const context = buildContext(); // Whatever context we want
3 const messages = [{ role: "user", content: userMessage }];
4
5 // Work until LLM doesn't invoke tools anymore
6 for (let i = 0; i < maxIterations; i++) {
7 // Abstract function to generate a call to LLM (API, etc)
8 const response = await llm.generate({
9 systemPrompt: buildSystemPrompt(context),
10 messages, // Supplies message history so that LLM knows the context
11 tools: toolRegistry, // Tells LLM what tools we have
12 });
13
14 if (response.toolCalls?.length > 0) {
15 for (const call of response.toolCalls) {
16 const result = await executeTool(call);
17 messages.push({ role: "tool", content: result });
18 }
19 } else {
20 return response.content; // Done — return final response
21 }
22 }
23
24 return "I couldn't complete this request. Please try again.";
25}

Більшість запитів завершуються за 1–3 ітерації. Максимум у 10 — це страховка від нескінченних циклів.

Системний промпт: учимо Мозок думати

У системному промпті ви задаєте характер агента, його можливості й обмеження. Це найважливіша частина «промпт-інжинірингу» в усій системі.

Хороший системний промпт має чотири розділи:

  1. Ідентичність і роль — хто цей агент? Навіщо він?
  2. Поточний контекст — яка сьогодні дата? Де користувач? На якій він сторінці?
  3. Правила відповідей — як форматувати відповіді? Яким тоном?
  4. Робота з інструментами — коли і як використовувати кожен із них

Спрощена версія:

1function buildSystemPrompt(context) {
2 return `You are Jinna, an AI assistant for invoice management.
3
4Current date: ${new Date().toLocaleDateString()}
5User is on this page: ${context.currentPage}
6
7Guidelines:
8- Be concise. Most responses should be 1-2 sentences.
9- Use tools to take action, don't just describe what you would do.
10- If the user's request is ambiguous, ask for clarification.
11- Always confirm destructive actions before executing.
12
13Available tools:
14- getInvoice: Retrieve invoice details
15- createInvoice: Create a new invoice
16- updateInvoice: Modify an existing invoice
17- deleteInvoice: Delete an invoice (CONFIRM FIRST)`;
18}

Трюк із контекстом сторінки часто недооцінюють. Фронтенд надсилає поточний URL і стан сторінки, тож агент знає, де зараз користувач. На сторінці рахунку «Видали цей рахунок» означає одне, а в списку рахунків — інше.

Реєстр інструментів: даємо Мозку руки

Інструменти — це функції, які агент може викликати. У кожного інструмента можуть бути:

  • name — унікальний ідентифікатор
  • description — що він робить (саме його читає LLM, щоб вирішити, коли брати інструмент)
  • parameters — JSON schema обов'язкових і необов'язкових вхідних даних
  • type — категорія для UX (read, write, destructive, external)
  • handler — сама функція, яку треба виконати

Тип інструмента визначає поведінку інтерфейсу:

  • read — виконується автоматично, без підтвердження (наприклад, getInvoice)
  • write — може показати спливне сповіщення (наприклад, updateInvoice)
  • destructive — завжди спершу просить підтвердження (наприклад, deleteInvoice)
  • external — попереджає, що дія виходить за межі поточної системи (наприклад, sendEmail)

Приклад реєстру інструментів. handler — ваша реальна бекенд-логіка, а description і parameters серіалізуються в текст для виклику LLM, і саме з них модель дізнається, що робить кожен інструмент:

1const toolRegistry = [
2 {
3 name: "getInvoice",
4 description: "Get details of a specific invoice by ID",
5 parameters: {
6 type: "object",
7 properties: {
8 invoiceId: { type: "string", description: "The invoice ID" },
9 },
10 required: ["invoiceId"],
11 },
12 type: "read",
13 handler: async ({ invoiceId }) => {
14 const invoice = await db.invoices.findById(invoiceId);
15 return JSON.stringify(invoice);
16 },
17 },
18 {
19 name: "createInvoice",
20 description: "Create a new invoice for a client",
21 parameters: {
22 type: "object",
23 properties: {
24 clientName: { type: "string" },
25 clientEmail: { type: "string" },
26 dueDate: { type: "string", description: "ISO date string" },
27 },
28 required: ["clientName"],
29 },
30 type: "write",
31 handler: async ({ clientName, clientEmail, dueDate }) => {
32 const invoice = await db.invoices.create({
33 clientName,
34 clientEmail,
35 dueDate,
36 });
37 return JSON.stringify(invoice);
38 },
39 },
40 {
41 name: "deleteInvoice",
42 description: "Permanently delete an invoice. Use with caution.",
43 parameters: {
44 type: "object",
45 properties: {
46 invoiceId: { type: "string" },
47 },
48 required: ["invoiceId"],
49 },
50 type: "destructive",
51 handler: async ({ invoiceId }) => {
52 await db.invoices.delete(invoiceId);
53 return `Invoice ${invoiceId} deleted`;
54 },
55 },
56];

Коли LLM вирішує, який інструмент узяти, вона читає саме опис. Не шкодуйте на описи часу. «Get details of a specific invoice by ID» краще, ніж просто «Get invoice»: так модель точно знає, що робить інструмент і що йому потрібно.

Керування контекстом: пам'ять Мозку

Агентам потрібна пам'ять. Без неї кожне повідомлення — чистий аркуш. Але всю історію в промпт не закинеш: у довгих розмовах цьому заважають ліміти токенів.

Я поєдную кілька видів контексту:

  1. Підсумок сесії — ковзне резюме розмови на ~250 слів. Його генеруємо заново щоразу, коли ШІ-агент завершує відповідь.
  2. Контекст сторінки — де користувач і на що дивиться саме зараз
  3. Історія чату — кілька звичайних повідомлень з усіма подробицями, щоб ШІ-агент міг природно вести розмову.

Підсумок сесії регулярно оновлюється:

1async function updateSessionSummary(messages, currentSummary) {
2 const recentMessages = messages.slice(-10); // Last 10 messages
3
4 const prompt = `Current summary: ${currentSummary || "None"}
5
6Recent conversation:
7${recentMessages.map((m) => `${m.role}: ${m.content}`).join("\n")}
8
9Write a brief summary (max 250 words) of the key points,
10decisions made, and current state. Focus on what's relevant
11for continuing the conversation.`;
12
13 return await llm.generate(prompt);
14}

Чому підсумок, а не вся історія? Ви ж не пам'ятаєте кожне слово кожної своєї розмови. Ви пам'ятаєте суть: ключові факти, рішення, поточний стан. Саме це й дає підсумок.

З контекстом сторінки простіше: це лише дані з фронтенду про поточний стан інтерфейсу. На якій сторінці користувач? Який рахунок переглядає? Які фільтри ввімкнено? Цей контекст свіжий у кожному повідомленні й коштує зовсім небагато токенів.

Разом ці 3 складники дають LLM достатньо контексту, щоб відповідати доречно й не губити нитку розмови.

Стрічка повідомлень: прозора робота агента

Користувачі мають бачити, що робить агент. Прозорість викликає довіру.

В інтерфейсі я використовую три типи повідомлень, хоча вам, залежно від задачі, може знадобитися більше чи менше:

  • thought — внутрішні міркування агента (сірим, можна згорнути)
  • tool — виклики інструментів і їхні результати (з іконкою інструмента)
  • response — остаточне повідомлення користувачеві (звичайна бульбашка чату)
1const timeline = [
2 {
3 type: "thought",
4 content: "User wants to create an invoice. I'll need to use createInvoice.",
5 timestamp: "2026-02-09T10:00:00Z",
6 },
7 {
8 type: "tool",
9 name: "createInvoice",
10 input: { clientName: "Acme Corp" },
11 output: { id: "inv_123", status: "draft" },
12 timestamp: "2026-02-09T10:00:01Z",
13 },
14 {
15 type: "response",
16 content:
17 "Done! Created a draft invoice for Acme Corp. Want me to add line items?",
18 timestamp: "2026-02-09T10:00:02Z",
19 },
20];

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

Налаштування Мозку: оптимізуємо шлях користувача

Збудувати агента — лише перший крок. Налаштовувати його під хороший UX доведеться постійно.

Чотири напрями для оптимізації:

1. Довжина відповідей

LLM обожнюють багатослів'я. Боріться із цим. Додайте явні інструкції на кшталт «Most responses should be 1-2 sentences» («більшість відповідей — 1–2 речення») і «Don't explain what you're about to do — just do it» («не пояснюй, що збираєшся зробити, — просто зроби»).

2. UX підтверджень

Коли агент має просити підтвердження, а коли просто діяти? Перед деструктивними діями агент питає завжди. А з операціями запису — по-різному: створити чернетку рахунку майже не ризиковано, а от надіслати лист — ризиковано. Під це й налаштуйте типи інструментів.

3. Обробка помилок

Що буде, якщо інструмент упаде? Агент має простими словами пояснити, що пішло не так, і запропонувати, що робити далі. «Не вдалося знайти рахунок із таким ID. Може, пошукати за ім'ям клієнта?»

4. Проактивні підказки

Чи має агент, виконавши задачу, пропонувати наступні кроки? Іноді так: «Рахунок створено. Надіслати його клієнтові?» Але не завжди — не треба набридати.

Чого я навчився: практичні поради

  • Починайте з 3–5 інструментів, а не з 30. Більше інструментів — більше плутанини для LLM. Додавайте нові, лише коли є чіткі сценарії використання.

  • Описи інструментів — це промпти. Не шкодуйте на них часу. Вони так само важливі, як і сам системний промпт.

  • Під час розробки логуйте все. Кожен промпт, кожен виклик інструмента, кожну відповідь. Рано чи пізно це знадобиться для налагодження, коли буде незрозуміло, як міркував ШІ-агент.

  • Тестуйте комбінації інструментів. Агенти поєднують інструменти так, як ви й не чекаєте. Щоб виконати «Створи рахунок і надішли його», createInvoice і sendEmail мають спрацювати разом.

  • Акуратно обробляйте часткові збої. Що, як рахунок створився, а лист не надіслався? Агент має сказати користувачеві, що вдалося, а не лише що не вдалося.

  • Підсумки сесії треба налаштовувати. Надто короткі — і контекст губиться. Надто довгі — і ви марнуєте токени. Для більшості випадків підходить ~250 слів.

  • Контекст сторінки часто недооцінюють. Коли агент знає, що користувач на /invoices/inv_123, усе змінюється. І «видали це» раптом стає однозначним.

Ширша картина: куди все рухається

ШІ-агенти вже багато в чому не поступаються людям. Іноді я ловлю себе на думці, що люди теж працюють як ШІ-агенти: у нас є свої системні промпти 🧠 (виховання), інструменти (навички) і контекст (пам'ять). Межа розмивається.

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

Кадр із мультфільму «Роботи» (2005)

Для тих, хто боїться, що ШІ замінить усе: так, ШІ міркує швидше за будь-яку людину. Але є те, що я називаю бар'єром експоненційної складності.

Згадайте, як буває з програмами: що більше ви будуєте, то тісніше все пов'язано й то експоненційно складнішою стає система. Сьогодні цілу компанію можна запустити самотужки, але з кожною новою функцією підтримувати її стає важче — експоненційно. Настає момент, коли простіше почати з нуля, ніж тягнути систему з мільйонами залежностей, if-else, процесів і людей у ланцюжку.

З будь-якою ШІ-системою те саме. Що більше її навчають, то експоненційно складнішою, а отже, менш гнучкою вона стає. У нас є LLM, які чудово дають раду конкретним і навіть загальним задачам, але «AGI» — справжній загальний інтелект — досі по той бік бар'єра експоненційної складності.

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

Висновок

Створити ШІ-агента — не магія, а архітектура.

Патерн Мозку дає чітку модель у голові: LLM + інструменти + цикл ReAct + контекст + системний промпт. У кожного компонента своя робота. Разом вони складаються в агента, що справді щось робить, а не лише балакає.

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

Приклади коду вище спрощені, але архітектура справжня. Вона вже працює в продакшні сервісу Jinna на Cloud Run і GCP. Якщо збудуєте щось схоже, буду радий почути — пишіть!