Что такое ИИ-агент в Telegram: собираем бота с визуализацией шагов за вечер

---

Telegram даёт ботам встроенный интерфейс для отображения хода работы ИИ-агента (программы, которая сама решает, какие действия выполнить для ответа), и собрать его можно за вечер на любом языке, используя HTTP-запросы без привязки к фреймворку.

Автор инструмента swift-claw описал на Хабре, как из возможностей Bot API собрать полноценный интерфейс агентного бота. Раньше на Хабре уже разбирали стриминг через sendMessageDraft и формат Rich Messages. Новый материал идёт дальше: связывает статусы инструментов, thinking-блоки и обработку отмены в единый рабочий цикл. Примеры написаны на HTTP и прикладном псевдокоде, поэтому переносятся в любой стек.

Что понадобится

• Telegram-бот с токеном (создаётся через BotFather)
• ID личного чата с ботом (можно получить через getUpdates)
• Любой инструмент для HTTP-запросов: curl, Postman, скрипт на Python, Node.js или чём угодно
• Доступ к методам sendRichMessageDraft и sendRichMessage в Bot API
• Примерно 30 минут на первый рабочий прототип

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

1. Создайте первый черновик с блоком состояния.

Метод sendRichMessageDraft работает в личном чате с ботом. В поле rich_message.html передайте тег <tg-thinking> с текстом текущего действия. Параметр can_stop включает встроенную кнопку Stop.

POST https://api.telegram.org/bot<TOKEN>/sendRichMessageDraft
Content-Type: application/json

{
  "chat_id": 123456789,
  "draft_id": 42,
  "can_stop": true,
  "rich_message": {
    "html": "<tg-thinking>Ищу тесты микрофонов в наушниках…</tg-thinking>"
  }
}

Замените <TOKEN> на токен бота, а 123456789 на реальный ID чата. Число 42 в draft_id условное: для каждого нового запроса пользователя выбирайте новый ненулевой ID, а для всех обновлений одного запуска сохраняйте прежний.

2. Обновляйте черновик при каждом новом шаге.

Повторите запрос с тем же draft_id, заменив текст внутри <tg-thinking>. Telegram обновит существующий черновик, а не создаст новый. Например, когда агент переходит от поиска к чтению страницы, отправьте «Читаю обзор Sony WH-1000XM5…».

Без обновлений черновик исчезнет через 30 секунд. Если инструмент работает долго, обновляйте черновик по таймеру, даже когда подпись не меняется.

3. Свяжите статусы с вызовами инструментов.

ИИ-агент при сложном запросе выполняет несколько действий: ищет источники, читает страницы, сравнивает данные. Одна общая подпись быстро перестаёт объяснять, что происходит. Покажите отдельные шаги и обновляйте их по мере выполнения.

Логика на псевдокоде (названия условные, к Telegram SDK не относятся):

при начале вызова инструмента:
  добавить шаг по ID вызова:
    подпись, цель, время начала, состояние «выполняется»
  запланировать обновление черновика

при завершении вызова инструмента:
  найти шаг по ID вызова
  записать результат и время выполнения
  запланировать обновление черновика

Из текущего списка шагов собирайте содержимое <tg-thinking> и отправляйте с прежним draft_id. Подпись «Ищу тесты микрофона Bose» объясняет действие понятно, без JSON с аргументами. После завершения покажите, что шаг выполнен, а если он упал, укажите ошибку. Иначе неудачный шаг останется в состоянии «выполняется», даже когда агент уже перешёл дальше.

Несколько событий могут прийти почти одновременно. Объединяйте такие изменения в одно обновление с актуальным состоянием всех шагов. Весь динамический текст экранируйте перед вставкой в HTML: поисковые запросы и заголовки страниц могут содержать символы разметки.

4. Сохраните готовый ответ отдельным сообщением.

Черновик подходит для промежуточного состояния. Чтобы результат остался в истории чата, отправьте его через sendRichMessage. Перед этим остановите таймер и отправку обновлений черновика.

POST https://api.telegram.org/bot<TOKEN>/sendRichMessage
Content-Type: application/json

{
  "chat_id": 123456789,
  "rich_message": {
    "html": "<p>Здесь готовое сравнение наушников со ссылками на источники.</p>"
  }
}

В rich_message.html передавайте текст без <tg-thinking>: этот блок разрешён только в черновиках. Текст ответа можно показывать в черновике по мере генерации, рядом с блоком состояния, но финальная отправка через sendRichMessage всё равно нужна: именно она сохраняет сообщение.

После первого полного прохода выйдите из чата и откройте его снова: сравнение должно остаться на месте.

5. Добавьте анимированные иконки.

Telegram рекомендует набор custom emoji AIActions для действий вроде поиска и обдумывания. Тег <tg-thinking> поддерживает такие эмодзи. Текстовые статусы работают и без анимации, но иконка делает состояние заметнее: пользователь мгновенно видит, ищет агент или читает страницу.

6. Обработайте нажатие кнопки Stop.

Параметр can_stop: true показывает кнопку, но нажатие нужно обработать на стороне бота. Храните draft_id вместе с задачей. Когда Telegram присылает событие отмены, найдите задачу по этому ID и остановите выполнение.

Что такое ИИ-агент в этом контексте?

ИИ-агент (agent) здесь не абстрактный «умный бот», а программа, которая сама решает, какие инструменты вызвать и в каком порядке, чтобы ответить на запрос. Пользователь просит сравнить наушники, агент сам запускает поиск, выбирает страницы, читает их и собирает ответ со ссылками. Каждое такое действие и есть «вызов инструмента», статус которого мы показываем в черновике.

Это отличает агентный (agentic) подход от обычного чат-бота, который просто генерирует текст: агент выполняет цепочку действий, и пользователь заслуживает видеть, на каком шаге процесс.

Что делать с этим прямо сейчас, по ролям

Авторам Дзена и контент-мейкерам. Если вы строите Telegram-бота, который готовит черновики постов или ищет фактуру, блок состояния покажет подписчикам, что бот работает, а не молчит. Это снижает число повторных запросов и повышает доверие к инструменту.

Маркетологам и продуктовым командам. Прозрачность работы агента напрямую влияет на удержание: пользователь, который видит прогресс, ждёт результата, а не закрывает чат. Механика реализуется через стандартный Bot API, без платных сервисов.

Разработчикам в РФ и СНГ. Примеры из источника написаны на чистом HTTP, без привязки к языку. Вы можете перенести их в Python, Go, PHP или любой стек, который используете. Из доступных в РФ языковых моделей для агентной логики подойдут YandexGPT и GigaChat, хотя конкретную интеграцию придётся настраивать под их API самостоятельно.

Блок состояния в Telegram делает невидимую работу агента видимой, и это тот случай, когда пять HTTP-запросов и один таймер меняют продукт сильнее, чем новая модель под капотом.