ИИ-агент в Telegram своими руками: бот, модель, база знаний

Бот это аккаунт Telegram, которым управляет программа, а не человек. Его выдает официальный бот @BotFather, без оплаты.

Управлять ботом будет n8n: конструктор, где агента собирают из блоков на схеме. Его лицензия fair-code (Sustainable Use License) разрешает ставить n8n на свой сервер и менять, но запрещает перепродавать как облачный сервис.

1. Откройте в Telegram чат с @BotFather и отправьте команду /newbot (новый бот).

2. Введите имя бота. Его видят клиенты, позже имя можно поменять.

3. Введите имя пользователя латиницей, оно должно заканчиваться на bot. Поменять его потом нельзя, поэтому берите понятное: название компании и bot.

4. Скопируйте токентокен Токен это кусочек текста: слово, часть слова или знак, с которыми работает языковая модель. Подробнее в словаре, который пришлет @BotFather. Токен это ключ от бота: документация Telegram просит хранить его как пароль и никому не показывать. Если ключ утек, его отзывают там же, в @BotFather.

5. В n8n создайте учетные данные Telegram и вставьте токен в поле «Access Token» (ключ доступаAPI-ключ API-ключ это секретная строка, по которой сервис нейросети узнает, какая программа к нему обращается и с чьего счета списать оплату за запросы. Подробнее в словаре).

Telegram передает сообщения в n8n через вебхук: это адрес, на который Telegram сам присылает каждое новое сообщение. По документации n8n адрес должен работать по HTTPS, а у бота может быть только один такой адрес. Поэтому n8n нужен на сервере с доменом, а для проверки удобно завести второго, тестового бота. Как поставить n8n, разобрано на странице об агенте на n8n.

Модель это нейросеть, которая читает сообщение и пишет ответ. Открытую модельмодель с открытыми весами Модель с открытыми весами (open-weights model) это нейросеть, файлы параметров которой можно скачать и запустить на своем оборудовании. Подробнее в словаре можно запустить на своем компьютере или сервере через Ollama, программу на лицензии MIT. Тогда переписка с клиентами не уходит к зарубежному поставщику.

1. Установите Ollama с сайта ollama.com для macOS, Windows или Linux и скачайте модель командой ollama pull с ее именем из библиотеки Ollama, например ollama pull gemma4:e2b из быстрого старта документации.

2. В n8n создайте новый сценарий и поставьте первым узлом «Telegram Trigger» (запуск по событию в Telegram) с событием «Message». Сценарий будет запускаться на каждое входящее сообщение.

3. Добавьте узел «AI Agent» (ИИ-агентИИ-агент ИИ-агент это нейросеть, которая не просто отвечает, а сама выполняет задачу по шагам: ищет данные, пользуется программами и проверяет результат. Подробнее в словаре). В поле «Prompt (User Message)» выберите «Define below» и выражением укажите текст сообщения из узла Telegram Trigger.

4. Подключите к агенту модель через узел «Ollama Chat Modelчат-модель Чат-модель это языковая модель, дообученная вести диалог: она понимает роли собеседников, следует инструкциям и отвечает на реплики, а не просто продолжает текст. Подробнее в словаре». В учетных данных Ollama поле «Base URL» по умолчанию равно http://localhost:11434. Если n8n и Ollama стоят в разных контейнерах Docker, документация n8n советует настроить переменную OLLAMA_HOST или OLLAMA_ORIGINS.

5. В параметрах агента откройте «System Message» (системное сообщение) и напишите инструкцию: кто агент, о чем отвечает, о чем молчит и когда зовет человека. От этого текста качество ответов зависит сильнее, чем от выбора модели.

6. Последним узлом поставьте «Telegram» с операцией «Send Message» (отправить сообщение). В «Chat ID» передайте номер чата из входящего сообщения, в «Text» ответ агента. В дополнительных полях выключите «Append n8n Attribution», иначе к каждому ответу добавится подпись n8n.

По документации n8n к узлу AI Agent подключают хотя бы один инструмент. На следующем шаге им станет база ваших документов. Короткий путь к первому агенту без Telegram описан в инструкции первого агента за вечер.

Чтобы агент отвечал по вашим ценам и условиям, ему дают базу документов. Перед ответом он ищет в ней подходящие фрагменты и отвечает по ним, модель при этом не обучают. Такой подход называют RAGRAG RAG это схема, в которой ИИ сначала находит нужные фрагменты в ваших документах, а потом отвечает, опираясь на них. Подробнее в словаре, по шагам он разобран на странице о том, как сделать RAG.

1. Сделайте отдельный сценарий загрузки: узел, который берет ваши файлы, и узел векторного хранилища «Simple Vector Store» в режиме «Insert Documents» (добавить документы). Векторное хранилище это база, где текст хранится в виде чисел для поиска по смыслу.

2. Подключите к хранилищу модель для векторов, например узел «Embeddings Ollama» с моделью nomic-embed-text, и узел «Default Data Loader», который режет текст на фрагменты. Для большинства задач документация n8n советует разбивку «Recursive Character Text Splitter».

3. В сценарии агента подключите то же хранилище в режиме «Retrieve Documents (As Tool for AI Agent)» и опишите, когда агенту им пользоваться, например: «цены, сроки и условия доставки». Модель для векторов должна быть та же, что при загрузке.

Ограничение: «Simple Vector Store» держит данные в памяти n8n, они пропадают при перезапуске, и документация советует его только для разработки. Перед работой с клиентами базу переносят в постоянную векторную базу.

Проверка занимает не меньше времени, чем сборка. Агент, который уверенно называет несуществующую цену, вредит сильнее, чем бот без ответа.

1. Подключите сценарий к тестовому боту и задайте вопросы из настоящей переписки с клиентами за последний месяц.

2. Разложите ответы на три группы: верный, неверный и выдуманный. Выдуманный ответ называет цену, срок или условие, которых нет в документах.

3. Допишите в «System Message», что отвечать, если в документах ответа нет, и когда передавать разговор менеджеру. Затем прогоните те же вопросы еще раз.

4. Если агент ходит по кругу, ограничьте число попыток параметром «Max Iterations»: по умолчанию модель пробует до 10 раз.

5. После проверки опубликуйте сценарий и подключите основного бота. Помните, что у бота один вебхук: тестовый и рабочий адреса n8n заменяют друг друга.

Список вопросов сохраните. По нему проверяют агента после каждой правки инструкции или смены модели, подробно на странице о тестировании агента.

Агент из этих четырех шагов отвечает по документам, но не видит ваших клиентов, сделок и остатков. Когда ответ зависит от CRM или 1С, агенту нужны инструменты с доступом к этим системам, права и журнал действий. Это уже работа разработчика.

Второй признак: агент собирает персональные данные. По 152-ФЗ данные граждан России собирают и хранят в базах на территории России, а до передачи за границу оператор подает уведомление в Роскомнадзор. Модель на своем сервере в России снимает вопрос передачи. Наш порядок хранения описан на странице о безопасности данных.

Тот же путь можно пройти во Flowise, визуальном конструкторе агентов на лицензии Apache 2.0. Как агент в Telegram ведет заявки в CRM, мы показали на странице интеграции с Telegram, а план запуска за 14 дней разобрали в статье блога.