Подключение больших языковых моделей (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 отправляет итоговое сообщение пользователю через метод
sendMessageTelegram 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.