Як я вбудував ШІ-агента в сервіс рахунків Jinna
Епоха, коли пристроями керуватимуть лише думкою, уже майже настала. А поки що чат 💬 зручніший за меню й форми, коли треба взаємодіяти із системами — і одне з одним.
Нещодавно я вбудував ШІ-агента в Jinna — безкоштовний сервіс, де виставляють рахунки. До речі, ви можете увійти й створювати там гарні✨ рахунки безкоштовно!
Це схоже на магію:
- Просите ШІ-агента виставити рахунок — і він його створює.
- Розуміє складні запити.
- Розбирається з неоднозначностями.
- Виконує ланцюжок змін і, якщо треба, дещо перепитує.
Нижче я ділюся тим, що знаю, щоб ви могли зробити схожого ШІ-агента для свого SaaS, продукту чи застосунку.
Стаття здебільшого технічна. Свої думки про ШІ-агентів я також висловлював на нещодавній панельній дискусії. Якщо будуєте щось схоже й потрібна допомога — пишіть.
Що ви дізнаєтеся:
- Як зрозуміти, чи потрібен вашому продукту ШІ-агент
- Як по-справжньому використовувати LLM у продукті (а не лише для чату)
- Як змусити LLM виконувати дії, а не тільки говорити
- Цикл ReAct — основний патерн, на якому тримаються ШІ-агенти
- Системні промпти, інструменти й керування контекстом
- Практичні поради з досвіду запуску в продакшн
Порада: на етапі планування дайте цю статтю Claude Code чи іншому агентові для програмування, яким користуєтеся, — він допоможе все продумати й правильно збудувати! Так працює підхід «спершу план», який я описав у статті «Як бути розробником в епоху ШІ».
Чи потрібен вашому продукту текстовий ШІ-асистент?
Рано чи пізно люди зрозуміють: доручити будь-яку роботу ШІ-агентам зручніше й ефективніше, ніж користуватися звичними вебінтерфейсами різних продуктів.
Це вже відбувається. Наприклад, замість того щоб заповнювати страхові документи в десятках форм, ви пишете в чаті, що вам треба, — як звернулися б до особистого консьєржа. Замість того щоб шукати авіаквитки, знову ж таки кажете, куди хочете полетіти й на яких умовах, — і отримуєте варіант саме під вас, ваш бюджет і ваші вподобання. Замість того щоб подавати заявку на візу... Ну, ви зрозуміли.
У 2026 році починається перехід від «традиційних» інтерфейсів до таких, що їх доповнюють ШІ-агенти: вони не лише консультують, а й справді виконують завдання. Кожному вебзастосунку варто подумати про власного агента — в одній із цих форм:
- ШІ-агент у чаті поряд із «традиційним» інтерфейсом — найуніверсальніший варіант. Потребує певної інженерної роботи з вашого боку, зате гарантує однаковий результат для всіх клієнтів.
- Відкритий API з документацією або MCP-сервер — інші ШІ-агенти користуються вашим API і працюють із сервісом напряму, без «рідного» чат-агента. Чужий агент стає споживачем сервісу так само, як люди.
У кожного підходу є плюси і мінуси:
| Параметр | Агент у чаті | API / MCP-сервер |
|---|---|---|
| Досвід користувача | Розмовний формат, легко освоїти | Залежить від агента-споживача, а в декого з користувачів навіть немає особистого ШІ-агента |
| Зусилля на розробку | Більші — інтерфейс чату + логіка агента + інструменти | Менші — задокументуйте API і випускайте. Найімовірніше, ви це вже зробили. |
| Контроль над UX | Повний — взаємодію проєктуєте ви | Мінімальний — ваш API інтерпретують інші агенти |
| Неоднозначні запити | Може ставити уточнювальні запитання | Залежить від ШІ-агента-споживача. Контракти API жорсткі |
| Охоплення | Лише ваші користувачі-люди * | Вашим сервісом може користуватися будь-який ШІ-агент |
* Чат вашого агента можна відкрити іншим агентам як окрему можливість — схоже на те, що Google описує у своєму протоколі Agent2Agent (A2A).
Чим ШІ-агент відрізняється від чат-бота?
Різниця проста: чат-боти відповідають, агенти діють.

Чат-бот отримує повідомлення та повертає відповідь. Агент отримує повідомлення, думає, що робити, діє через інструменти, дивиться на результат і повторює все це, доки не виконає завдання.
Різниця в псевдокоді:
1// Chatbot2function chatbot(message) {3 return llm.generate(message);4}5 6// Agent7function agent(message, context) {8 while (!done) {9 const thought = llm.think(message, context); // any capable LLM10 if (thought.needsTool) {11 const result = executeTool(thought.tool);12 context.add(result);13 } else {14 return thought.response;15 }16 }17}Агенти користуються так званими «інструментами» (tools), ухвалюють рішення і пам'ятають контекст. Вони крутяться в циклі, доки не переконають себе, що впоралися з початковим запитом чи запитанням. Такий агент — радше колега, ніж розумний пошуковий рядок.
Інструменти тут — це заздалегідь запрограмовані дії з документацією. Інакше кажучи, це перелік умінь, які ви даєте своєму ШІ-агентові, наприклад:
- Переглядати, створювати, редагувати й видаляти об'єкти та сутності вашої системи
- Просити користувача щось увести.
- Викликати ендпоінт API.
- Усе що завгодно!
Будь-що! Спираючись на документацію, ШІ-агент сам вирішує, який інструмент узяти, залежно від того, що є в його «контексті» (про це далі).
Тут добре працює метафора мозку: на вхід надходить інформація, мозок пропускає її крізь шари міркувань, вирішує, діяти чи відповісти, а якщо треба — заходить на ще одне коло, уже з новими даними. Це система зі зворотним зв'язком, а не одноразовий запит.
Архітектура: огляд системи
Мозок складається із шести основних компонентів:
- Провайдер LLM — «рушій міркувань». Його легко замінити: Gemini, Claude, OpenAI, що завгодно.
- Системний промпт — «характер і правила». Пояснює моделі, хто вона така і як має поводитися.
- Реєстр інструментів — «руки». Функції, які агент може викликати, щоб справді щось робити.
- Цикл ReAct — цикл «подумай — зроби — подивись». Основний патерн виконання.
- Керування контекстом — «пам'ять». Що агент пам'ятає про розмову.
- Стрічка повідомлень — «журнал розмови». Що бачить користувач.
Уявіть їх як ділянки мозку, що працюють злагоджено. Кожна виконує свою роботу, а разом вони дають цілісну поведінку.
LLM (власне виклик API моделі) — ядро міркувань у цій системі: вона отримує вхідні дані й ухвалює рішення. Системний промпт — це виховання і навчання агента: він формує, як думає LLM, і дає їй самоусвідомлення. Інструменти — моторна кора: вони перетворюють рішення на дії. Контекст — пам'ять: усе важливе з минулого чи з поточної розмови (скажімо, яку вебсторінку зараз відкрито). Контекстне вікно — скільки LLM може охопити й «запам'ятати», перш ніж здатися та видати остаточне рішення. А цикл ReAct — свідоме мислення: ітеративний процес, у якому модель крок за кроком розв'язує задачу.
Коли каркас системи готовий, починається справжня людська (розробницька) робота: Мозок треба налаштувати. Але про все по черзі — почнімо із самого Мозку.
Вибір Мозку, або яку LLM-модель узяти
LLM можна замінити: та сама архітектура працює з Gemini, Claude, OpenAI чи будь-яким іншим провайдером. Але від вибору моделі залежать UX і вартість.
Я користувався Gemini Flash і Pro, і різниця між ними суттєва:
| Параметр | Gemini Flash | Gemini Pro |
|---|---|---|
| Швидкість | Швидка | Повільніша |
| Вартість | Дешевша | Дорожча |
| Прості задачі | Добре дає раду | З гармати по горобцях |
| Неоднозначні запити | Може вгадати й виконати | Частіше перепитує |
| Складні міркування | Буває, що «поспішає» | Обмірковує задачу |
| Загальна оцінка ⭐️ | Буває ненадійною | Чудова, але повільніша |

Справжню різницю видно в крайніх випадках. Flash схильна виконувати те, що, як їй здається, ви маєте на увазі, а якщо задача надто складна — опускає руки. Pro частіше перепитує, коли не певна, обробляє більше контексту й розбирається з неоднозначністю на кілька рівнів глибше. Жодна з них не права на всі сто: Flash іноді вгадує правильно й заощаджує час, а Pro іноді перемудровує або все одно пропускає деталі, що лежать на поверхні.
Практичні поради:
- Для прототипу починайте з Flash — швидкі ітерації, низька вартість
- Перевіряйте крайні випадки на Pro, щоб побачити, що ви пропускаєте
- Можна брати Flash для простих операцій читання, а Pro — для запису та складної логіки
- Або: за замовчуванням працювати на Flash, а для багатокрокових задач перемикатися на Pro
Цикл ReAct: як думає Мозок
ReAct означає «Reason + Act» — «міркуй і дій». Саме на цьому патерні тримається робота агентів.
Цикл:
- Аналіз — оцінити запит користувача й поточний контекст
- Рішення — визначити, чи потрібен інструмент, чи можна відповісти одразу
- Виконання — якщо інструмент потрібен, викликати його
- Спостереження — подивитися, що вийшло
- Повтор або відповідь — або продовжити (з новою інформацією), або повернути остаточну відповідь
Реальний приклад. Користувач пише: «Створи новий рахунок для 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 want3 const messages = [{ role: "user", content: userMessage }];4 5 // Work until LLM doesn't invoke tools anymore6 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 context11 tools: toolRegistry, // Tells LLM what tools we have12 });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 response21 }22 }23 24 return "I couldn't complete this request. Please try again.";25}Більшість запитів завершуються за 1–3 ітерації. Максимум у 10 — це страховка від нескінченних циклів.
Системний промпт: учимо Мозок думати
У системному промпті ви задаєте характер агента, його можливості й обмеження. Це найважливіша частина «промпт-інжинірингу» в усій системі.
Хороший системний промпт має чотири розділи:
- Ідентичність і роль — хто цей агент? Навіщо він?
- Поточний контекст — яка сьогодні дата? Де користувач? На якій він сторінці?
- Правила відповідей — як форматувати відповіді? Яким тоном?
- Робота з інструментами — коли і як використовувати кожен із них
Спрощена версія:
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 details15- createInvoice: Create a new invoice16- updateInvoice: Modify an existing invoice17- 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»: так модель точно знає, що робить інструмент і що йому потрібно.
Керування контекстом: пам'ять Мозку
Агентам потрібна пам'ять. Без неї кожне повідомлення — чистий аркуш. Але всю історію в промпт не закинеш: у довгих розмовах цьому заважають ліміти токенів.
Я поєдную кілька видів контексту:
- Підсумок сесії — ковзне резюме розмови на ~250 слів. Його генеруємо заново щоразу, коли ШІ-агент завершує відповідь.
- Контекст сторінки — де користувач і на що дивиться саме зараз
- Історія чату — кілька звичайних повідомлень з усіма подробицями, щоб ШІ-агент міг природно вести розмову.
Підсумок сесії регулярно оновлюється:
1async function updateSessionSummary(messages, currentSummary) {2 const recentMessages = messages.slice(-10); // Last 10 messages3 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 relevant11for 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, усе змінюється. І «видали це» раптом стає однозначним.
Ширша картина: куди все рухається
ШІ-агенти вже багато в чому не поступаються людям. Іноді я ловлю себе на думці, що люди теж працюють як ШІ-агенти: у нас є свої системні промпти 🧠 (виховання), інструменти (навички) і контекст (пам'ять). Межа розмивається.
Скоро ми навчатимемо власних роботів, як у мультфільмі «Роботи». Навчання і дорослішання там показано напрочуд близько до того, як це працює насправді.

Для тих, хто боїться, що ШІ замінить усе: так, ШІ міркує швидше за будь-яку людину. Але є те, що я називаю бар'єром експоненційної складності.
Згадайте, як буває з програмами: що більше ви будуєте, то тісніше все пов'язано й то експоненційно складнішою стає система. Сьогодні цілу компанію можна запустити самотужки, але з кожною новою функцією підтримувати її стає важче — експоненційно. Настає момент, коли простіше почати з нуля, ніж тягнути систему з мільйонами залежностей, if-else, процесів і людей у ланцюжку.
З будь-якою ШІ-системою те саме. Що більше її навчають, то експоненційно складнішою, а отже, менш гнучкою вона стає. У нас є LLM, які чудово дають раду конкретним і навіть загальним задачам, але «AGI» — справжній загальний інтелект — досі по той бік бар'єра експоненційної складності.
Тож будуйте своїх агентів. Вони візьмуть на себе ваші рахунки, підтримку клієнтів, конвеєри даних. Але вашого судження і «людського чуття» вони не замінять — принаймні поки що.
Висновок
Створити ШІ-агента — не магія, а архітектура.
Патерн Мозку дає чітку модель у голові: LLM + інструменти + цикл ReAct + контекст + системний промпт. У кожного компонента своя робота. Разом вони складаються в агента, що справді щось робить, а не лише балакає.
Добре продумайте кожен компонент — і отримаєте агента, схожого на тямущого колегу, а не на розгублене автодоповнення.
Приклади коду вище спрощені, але архітектура справжня. Вона вже працює в продакшні сервісу Jinna на Cloud Run і GCP. Якщо збудуєте щось схоже, буду радий почути — пишіть!