ОБУЧЕНИЕ

ТЕСТОВЫЙ МАТЕРИАЛ: как связать AI-агента с Telegram-ботом

Проверочная статья раздела ОБУЧЕНИЕ — показывает вёрстку карточки, обложку и заголовки. Удаляется после первой настоящей публикации.

Автор: СТАТЕЙНИК12 min read

Источник: Telegram Bot API

Абстрактная иллюстрация: цифровая сеть агентов, соединённых с мобильным устройством.

Краткий ответ

Чтобы связать AI-агента с Telegram-ботом, нужно три вещи: бот в Telegram, код, который принимает сообщения, и вызов модели по этому сообщению. Агент — это не отдельный сервис, а слой логики между Telegram и моделью: он хранит историю диалога, решает, что делать с ответом модели, и отправляет результат обратно в чат. Минимальная рабочая схема занимает около 120 строк кода и запускается за час.

Чему вы научитесь

  • Создавать бота через @BotFather и получать токен
  • Принимать сообщения long polling без внешнего сервера
  • Вызывать модель и возвращать ответ в чат
  • Понимать, где граница между ботом и агентом

Примените за 40 минут

Экономите 20 часов — столько уходит, если разбираться с Bot API и подключением модели с нуля.

Уровень: Новичок

Зачем это нужно

Telegram — самый массовый мессенджер в России и СНГ. По данным Mediascope, аудитория Telegram в стране превысила 82 млн человек. Если ваш продукт или услуга должны отвечать клиентам в чате, бот — самый быстрый способ это сделать без отдельного приложения и без операторов на линии.

AI-агент добавляет к обычному боту главное: он не раздаёт заготовки, а формирует ответ под конкретный вопрос. Обычный бот работает по правилам, агент — по смыслу.

Подход Ответ на нестандартный вопрос Стоимость
Без AI «Нажмите кнопку 2» или тишина Только разработка
Без AI + человек Оператор отвечает вручную От 300 ₽/час
С AI Смысловой ответ за секунды ~300 ₽ на 1000 запросов

Что это такое

Бот — это программа, зарегистрированная в Telegram под специальным именем. Она не «понимает» сообщения, а получает их как структурированные данные и отвечает по правилам.

Агент — надстройка над ботом: та же программа, но с моделью внутри и с памятью диалога.

Ключевое различие в одном предложении: бот отвечает по правилам, агент отвечает по смыслу.

Технически агент — это цикл из четырёх шагов:

Сообщение → история → модель → проверка → ответ

Сценарии применения

  1. Техподдержка товара — бот отвечает на частые вопросы про доставку и оплату
  2. Квалификация лидов — агент задаёт вопросы и отбирает целевых
  3. Внутренний ассистент — команда спрашивает бот про регламенты
  4. Сбор обратной связи — бот проводит короткий опрос и суммирует ответы
  5. Агент-автоматизатор — бот запускает действия в других системах

Пошаговая инструкция

Шаг 1. Создайте бота

Напишите @BotFather, команда /newbot, задайте имя и username. Он выдаст токен вида 123456:ABC-DEF.... Это ваш пароль — не публикуйте его.

Шаг 2. Примите первое сообщение

Используйте long polling: сервер не отправляет вам ничего, вы сами спрашиваете о новых сообщениях. Это избавляет от публичного адреса.

import requests

TOKEN = "<YOUR_TOKEN>"

def get_updates(offset=0):
    url = f"https://api.telegram.org/bot{TOKEN}/getUpdates"
    return requests.get(url, params={"offset": offset, "timeout": 30}).json()

Шаг 3. Вызовите модель

Соберите историю диалога и передайте её модели. Ограничивайте историю — иначе растёт цена и падает точность.

def ask_model(history):
    response = requests.post(
        "https://openrouter.ai/api/v1/chat/completions",
        headers={"Authorization": "Bearer <YOUR_KEY>"},
        json={
            "model": "anthropic/claude-sonnet-4",
            "messages": history,
            "max_tokens": 1000,
        },
    )
    return response.json()["choices"][0]["message"]["content"]

Шаг 4. Верните ответ

def send_message(chat_id, text):
    requests.post(
        f"https://api.telegram.org/bot{TOKEN}/sendMessage",
        json={"chat_id": chat_id, "text": text},
    )

Шаг 5. Сведите в цикл

offset = 0
while True:
    result = get_updates(offset)
    for update in result["result"]:
        offset = update["update_id"] + 1
        chat_id = update["message"]["chat"]["id"]
        history.append({"role": "user", "content": update["message"]["text"]})
        send_message(chat_id, ask_model(history))

Шаг 6. Ограничьте доступ

Добавьте проверку chat_id по белому списку. Без неё бот отвечает любому, кто его нашёл.

Что здесь не сработает

Задача Решение Почему
Отвечать на сложные юридические вопросы Не делегировать модели Ответственность на бизнесе, а не на боте
Мгновенная реакция в 03:00 ночи Спасает только модель Long polling засыпает вместе с процессом
Нагрузка больше 50 сообщений в секунду Нужен вебхук и очередь Long polling не масштабируется
Диалог длиннее 20 сообщений Нужна память в базе История в памяти процесса теряется при рестарте
Экономия на модельной ключе Урезать max_tokens Дешёвые ответы хуже отвечают на сложные вопросы
Развёртывание на 3 минутах Нужен нормальный хостинг Токен и ключ нельзя хранить в коде

Типичные ошибки

Токен в коде — выглядит так: TOKEN = "123456:ABC-DEF". Сосед по репозиторию получает доступ к вашему боту. Исправление: переменная окружения os.environ["TELEGRAM_BOT_TOKEN"].

История растёт бесконечно — через неделю вы платите в 20 раз больше за один и тот же вопрос. Исправление: обрезайте до последних 10–15 сообщений.

Бот без белого списка — через неделю накопятся спам-сообщения и жалобы на ваш username. Исправление: проверка chat_id до обработки.

Ошибки модели молча проглатываются — response.json() падает на нестандартном ответе. Исправление: обёртка try/except и лог.

Цикл без задержки — вы отправляете тысячи запросов в секунду и ловите 429 Too Many Requests. Исправление: time.sleep(1) в конце итерации.

Нет логов — когда что-то сломается, разбираться нечем. Исправление: пишите в файл или в сервис логов.

Метрики

Считайте три вещи:

Экономия часов = количество вопросов × среднее время ответа оператора
Стоимость запроса = цена за 1M токенов × токены на ответ / 1_000_000
Окупаемость = экономия часов × стоимость часа / (разработка + ежемесячные расходы)

Чек-лист

  • Бот создан через @BotFather
  • Токен в переменной окружения, не в коде
  • Long polling работает, ответ приходит в чат
  • История диалога ограничена
  • Белый список chat_id настроен
  • Ошибки логируются
  • Ключ модели в переменной окружения

Источники

← Все практические материалы