Telegram-бот + LLM Tool Calling на Node.js: зв'язуємо OpenAI API та бізнес-логіку

Підключення великих мовних моделей (LLM) до Telegram-бот а напряму через звичайний текстовий промпт швидко впирається в обмеження: модель не має доступу до вашої бази даних, не вміє перевіряти статуси замовлень і не може створювати бронювання в CRM. Рішенням цієї проблеми є механізм Tool Calling (Function Calling).

У цій статті ми розберемо, як побудувати надійний цикл (Agent Loop) на Node.js, коли модель сама приймає рішення викликати функцію get_order або create_booking, а сервер виконує код і повертає результат назад моделі для формування підсумкової відповіді клієнту.

Архітектура взаємодії: Telegram, Node.js та LLM

Головний принцип побудови безпечних AI-ботів — суворе розділення відповідальності. Мовна модель є лише «мозком для прийняття рішень» (Reasoning Engine), але вона не має прямого доступу до зовнішніх API, вашої бази даних і тим більше до Telegram Bot API.

  • Telegram Client надсилає Webhook на ваш Node.js сервер.
  • Node.js Backend приймає update_id, перевіряє авторизацію та передає історію повідомлень у LLM разом із описом доступних інструментів (Tool Schemas).
  • OpenAI LLM повертає не текст, а інструкцію tool_calls з ім'ям функції та валідним JSON-аргументом.
  • Node.js Backend виконує локальний код (запит до DB/CRM), отримує результат і надсилає його назад у LLM.
  • OpenAI LLM генерує фінальну текстову відповідь для користувача на основі отриманих даних.
  • Node.js Backend надсилає підсумкове повідомлення користувачеві через метод sendMessage Telegram Bot API.

Чому модель ніколи не повинна знати Telegram Bot Token

Правило безпеки: Ніколи не передавайте TELEGRAM_BOT_TOKEN у системний промпт або в параметри контексту LLM. Моделі вразливі до атак типу Prompt Injection. Якщо зловмисник змусить модель видати системний промпт або виконати довільний код, скомпрометований токен дозволить повністю захопити управління вашим ботом.

Токен Telegram повинен перебувати виключно у змінних оточення (process.env.TELEGRAM_BOT_TOKEN) вашого Node.js-середовища. Усі звернення до API Telegram виконуються тільки бекендом.

Визначення схем інструментів (Tools Definition)

Для того щоб модель розуміла, які дії їй доступні, ми описуємо інструменти у форматі JSON Schema. Розглянемо два часті сценарії: отримання статусу замовлення (get_order) та створення запису на послугу (create_booking).

// tools.js
export const toolsSchema = [
{
type: "function",
function: {
name: "get_order",
description: "Получить информацию о статусе и составе заказа по его ID",
parameters: {
type: "object",
properties: {
order_id: {
type: "string",
description: "Идентификатор заказа, например, ORD-12345"
}
},
required: ["order_id"]
}
}
},
{
type: "function",
function: {
name: "create_booking",
description: "Забронировать слот на услугу для клиента",
parameters: {
type: "object",
properties: {
service_name: {
type: "string",
description: "Название услуги (например, 'Консультация' или 'Стрижка')"
},
date_time: {
type: "string",
description: "Дата и время в ISO формате, например 2025-04-10T15:00:00"
},
customer_name: {
type: "string",
description: "Имя клиента"
}
},
required: ["service_name", "date_time", "customer_name"]
}
}
}
];

Реалізація циклу Tool Calling (Agent Loop)

Після отримання відповіді від моделі необхідно перевірити поле finish_reason або наявність масиву tool_calls. Якщо модель вирішила викликати функцію, ми виконуємо відповідний обробник, додаємо його відповідь у масив повідомлень із роллю tool і повторюємо запит до LLM.

// agent.js
import OpenAI from "openai";
import { toolsSchema } from "./tools.js";

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

// Имитация работы с базой данных / CRM
async function executeTool(name, args) {
if (name === "get_order") {
// В реальном проекте: SELECT * FROM orders WHERE id = args.order_id
if (args.order_id === "ORD-12345") {
return JSON.stringify({ status: "shipped", items: ["Ноутбук"], delivery_date: "2025-03-30" });
}
return JSON.stringify({ error: "Заказ не найден" });
}

if (name === "create_booking") {
// В реальном проекте: INSERT INTO bookings ...
const bookingId = "BK-" + Math.floor(1000 + Math.random() * 9000);
return JSON.stringify({ success: true, booking_id: bookingId, details: args });
}

throw new Error(`Неизвестный инструмент: ${name}`);
}

export async function processUserMessage(userMessage, chatHistory = []) {
const messages = [
{ role: "system", content: "Вы — вежливый ассистент поддержки. Используйте инструменты для получения данных и создания записей." },
...chatHistory,
{ role: "user", content: userMessage }
];

let runner = true;
let iterations = 0;
const maxIterations = 5; // Защита от бесконечного цикла

while (runner && iterations < maxIterations) {
iterations++;
const response = await openai.chat.completions.create({
model: "gpt-4o-mini",
messages: messages,
tools: toolsSchema,
tool_choice: "auto"
});

const responseMessage = response.choices[0].message;
messages.push(responseMessage);

if (responseMessage.tool_calls && responseMessage.tool_calls.length > 0) {
for (const toolCall of responseMessage.tool_calls) {
const functionName = toolCall.function.name;
const functionArgs = JSON.parse(toolCall.function.arguments);

const functionResult = await executeTool(functionName, functionArgs);

messages.push({
tool_call_id: toolCall.id,
role: "tool",
name: functionName,
content: functionResult
});
}
} else {
runner = false;
return responseMessage.content;
}
}

return "К сожалению, не удалось обработать запрос. Попробуйте позже.";
}

Інтеграція з Telegram Webhook та дедуплікація

Telegram у разі позаштатних ситуацій або затримок відповіді сервера понад 5 секунд може повторно надсилати один і той самий Update. Щоб уникнути дублювання викликів функцій (наприклад, повторного створення бронювання), реалізуємо перевірку update_id та валідацію заголовка X-Telegram-Bot-Api-Secret-Token.

// server.js
import express from "express";
import { processUserMessage } from "./agent.js";

const app = express();
app.use(express.json());

const processedUpdates = new Set();
const BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
const SECRET_TOKEN = process.env.TELEGRAM_SECRET_TOKEN;

async function sendTelegramMessage(chatId, text) {
const url = `https://api.telegram.org/bot${BOT_TOKEN}/sendMessage`;
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chat_id: chatId,
text: text,
parse_mode: "HTML"
})
});

const data = await response.json();
if (!response.ok || !data.ok) {
console.error("Telegram API Error:", data);
}
}

app.post("/webhook", async (req, res) => {
const incomingSecret = req.headers["x-telegram-bot-api-secret-token"];
if (incomingSecret !== SECRET_TOKEN) {
return res.status(403).send("Unauthorized");
}

const update = req.body;

if (!update || !update.update_id) {
return res.status(400).send("Bad Request");
}

// Идемпотентность: пропуск уже обработанных update_id
if (processedUpdates.has(update.update_id)) {
return res.status(200).send("OK");
}
processedUpdates.add(update.update_id);

// Очистка старых update_id для предотвращения утечки памяти
if (processedUpdates.size > 10000) {
const firstItem = processedUpdates.values().next().value;
processedUpdates.delete(firstItem);
}

// Отвечаем Telegram 200 OK незамедлительно, чтобы избежать таймаута
res.status(200).send("OK");

if (update.message && update.message.text) {
const chatId = update.message.chat.id;
const userText = update.message.text;

try {
const replyText = await processUserMessage(userText);
await sendTelegramMessage(chatId, replyText);
} catch (error) {
console.error("Error processing agent loop:", error);
await sendTelegramMessage(chatId, "Произошла ошибка при обработке вашего запроса.");
}
}
});

app.listen(3000, () => {
console.log("Server started on port 3000");
});

Часті помилки під час роботи з Tool Calling

  • Затримка відповіді (Timeout 5000ms): LLM із викликом функцій може генерувати відповідь від 2 до 8 секунд. Обов'язково повертайте Telegram статус 200 OK одразу після прийому Webhook, а обробку та надсилання sendMessage виконуйте асинхронно.
  • Відсутність валідації аргументів: LLM може згенерувати невалідний JSON або передати рядковий аргумент замість числа. Обов'язково обгортайте JSON.parse() у блок try...catch і перевіряйте типи даних перед передачею в бізнес-логіку.
  • Відсутність ліміту ітерацій: Якщо модель почне постійно викликати функції по колу, це призведе до вичерпання балансу API. Завжди обмежуйте while лічильником (наприклад, не більше 5 ітерацій).

Якщо вам потрібна професійна розробка складних AI-ботів та інтеграція з CRM, зверніться до фахівців BotCreator.

Нові статті — у Telegram

Розбираємо, що автоматизувати в бізнесі та як це працює на практиці. Без спаму.