Телеграм-бот на aiogram 3 с ИИ-агентом: от BotFather до работающего бота

aiogram — самая популярная библиотека для телеграм-ботов на Python в русскоязычном сегменте. Её ищут больше трёх с половиной тысяч раз в месяц. Современная версия — третья: на август 2026 года это aiogram 3.31, нужен Python от 3.10.

Бота на aiogram часто просят написать нейросеть. Первый код обычно не запускается, и причина почти всегда одна.

Почему код от нейросети не работает

В интернете огромный пласт примеров на aiogram 2. Модели учились на нём и охотно выдают код, который на aiogram 3 падает сразу:

aiogram 2 (не работает)	aiogram 3
Dispatcher(bot)	Dispatcher(), бот передаётся в start_polling
@dp.message_handler(commands=['start'])	@dp.message(CommandStart())
executor.start_polling(dp)	await dp.start_polling(bot) внутри asyncio.run

Если видишь в коде executor или message_handler, это вторая версия. Проще сразу написать модели: «aiogram 3, Python 3.12».

Минимальный рабочий бот

1. В Telegram открой @BotFather, отправь /newbot, задай имя и получи токен.
2. Установи библиотеку: pip install aiogram.
3. Создай bot.py:

import asyncio
import os

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message

dp = Dispatcher()


@dp.message(CommandStart())
async def start(message: Message):
    await message.answer("Привет! Я работаю.")


@dp.message()
async def echo(message: Message):
    await message.answer(message.text or "Пришли текст")


async def main():
    bot = Bot(token=os.environ["BOT_TOKEN"])
    await dp.start_polling(bot)


asyncio.run(main())

4. Задай переменную окружения BOT_TOKEN с токеном и запусти python bot.py.

Токен не пиши прямо в код и не выкладывай в репозиторий: с ним любой может управлять ботом. Если токен утёк, выпусти новый в BotFather командой /revoke.

Частые ошибки

TelegramUnauthorizedError — неверный токен или токен отозван.

TelegramConflictError с текстом про другой запрос getUpdates — бот запущен дважды. Обычно второй экземпляр остался в другом окне терминала или на сервере.

Бот молчит в группе — по умолчанию у ботов включён режим приватности, и в группах они видят только команды и ответы на свои сообщения. Режим меняется в BotFather.

AttributeError на message.text — пришёл стикер или фото, у них нет текста. В примере выше это закрыто через or.

Как писать бота вместе с агентом

Чат выдаёт код, который надо копировать, запускать и возвращать ошибку обратно. Агент делает этот цикл сам.

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

• «Создай бота на aiogram 3: команда /start, меню из трёх кнопок, запись заявок в leads.csv. Запусти и проверь, что стартует без ошибок»;
• «Добавь состояние (FSM): бот спрашивает имя, телефон и услугу, потом присылает мне сводку»;
• «Бот падает с TelegramConflictError, найди, где запущен второй экземпляр»;
• «Напиши requirements.txt и инструкцию, как запустить бота на сервере через systemd».

Агент пишет код, ставит зависимости, запускает бота, читает вывод и правит, пока не заработает. Проверить нажатия кнопок в самом Telegram всё равно придётся тебе.

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

Если бот должен ещё и отвечать нейросетью, проще всего подключить к нему OpenAI-совместимый API: локальный llama-server или облачного провайдера. А если нужен доступ агента к самому Telegram, есть Telegram MCP.

С чего начать

Получи токен в BotFather, скачай Доку, создай пустую папку и попроси сделать бота с командой /start на aiogram 3. Когда он ответит в Telegram, добавляй функции по одной.