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

Разбираем, что автоматизировать в бизнесе и как это работает на практике. Без спама.