An autonomous AI agent for Telegram that chats on your behalf — like a real person.
It learns from your chat history, holds conversations, and carries out tasks using tools (function calling).
dreamAgent connects to your personal Telegram account via MTProto (Telethon), studies how you write, and then answers in your private chats on its own: with human-like delays, "typing…" indicators, reactions, deliberate silence — and it resists attempts to jailbreak or manipulate the bot.
Beyond auto-replies, the agent works as a full tool-using assistant (in the spirit of function calling / MCP): it searches contacts, reads and writes to any chats, sets reactions, deletes and edits messages, schedules delayed actions, and drives a conversation in a specific chat toward a set goal.
| 🧠 Learns from your chats | Reads your last ~10 private chats (only your messages) and builds a style profile: phrase length, vocabulary, emoji usage, response tempo, signature phrases |
| 💬 Autonomous replies | Answers DMs on your behalf (bots/groups/channels are ignored): human-like timing, "typing…", multi-message replies, reactions, or deliberate silence |
| 🛠️ Tools | Function-calling loop: contact search, history reading, sending, reactions, delete/edit, scheduling, blocking |
| 🎯 Goal-driven dialogues | For any chat you can set a goal ("warm them up", "invite for coffee") — the agent continues the conversation and reports back |
| 📋 Tasks | "Text Sasha about the salary", "remind Ane in an hour" — from web UI or command bot; the agent picks the timing and wording, then reports back |
| 🎙️ Multimodal | Voice messages and video circles transcribed offline (faster-whisper), photos understood by a vision model |
| ⚙️ Flexible settings | Global instruction + per-chat instructions, allow/block lists, working schedule, LLM provider and model selection |
| 🤖 Command bot | Control the agent right from Telegram through your own bot with deep-link linking |
| 🔐 Security | Argon2 hashes, signed httponly sessions, CSRF, IDOR protection, ORM parameterization, rate limiting, encrypted Telethon session files |
| 🚦 LLM gateway | Request queue honoring provider rate limits, retries with backoff |
git clone https://github.com/dreamcatchered/dreamAgent.git
cd dreamAgent
# 1. Dependencies (Python 3.11+)
pip install -r requirements.txt
# 2. Configuration
cp .env.example .env
# fill in TG_API_ID/TG_API_HASH (https://my.telegram.org),
# LLM provider tokens, SECRET_KEY, admin password
# 3. Run
python run.pyOpen:
- App: http://localhost:8000
- Admin panel: http://localhost:8000/admin
On first launch faster-whisper downloads the model (~145 MB for base);
if unavailable, the app still works and voice messages are marked unrecognized.
Warning
This project automates actions on behalf of your own Telegram account. Use it responsibly and legally: no spam, mass mailing, scams or deception about who people are talking to. Account automation may violate the Telegram Terms of Service. You do this at your own risk. Distributed as-is for educational purposes.
Автономный ИИ-агент для Telegram, который общается в чатах за вас — как живой человек.
Учится на вашей переписке, ведёт диалоги, выполняет поручения с помощью инструментов (tools).
dreamAgent подключается к вашему личному Telegram-аккаунту через MTProto (Telethon), изучает вашу манеру общения и дальше сам отвечает в личных чатах: с человекоподобными задержками, «печатает…», реакциями, осознанным молчанием — и устойчив к попыткам собеседника «взломать» бота.
Помимо автоответов агент работает как полноценный ассистент с инструментами (в духе function calling / MCP): ищет контакты, читает и пишет в любые чаты, ставит реакции, удаляет и редактирует сообщения, планирует отложенные действия, ведёт диалог в конкретном чате к заданной цели.
| 🧠 Обучение на переписках | Читает последние ~10 ваших личных чатов (только ваши сообщения) и строит профиль стиля: длина фраз, лексика, эмодзи, темп ответов, фирменные обороты |
| 💬 Автономные ответы | Отвечает за вас в личке с людьми (боты/группы/каналы игнорируются): тайминги как у человека, «печатает…», несколько сообщений подряд, реакции или осознанное молчание |
| 🛠️ Инструменты (tools) | Function-calling цикл: поиск контактов, чтение истории, отправка, реакции, удаление/редактирование, планирование, блокировки |
| 🎯 Диалоги с целью | Для конкретного чата можно задать цель («разговорить», «пригласить на кофе») — агент сам продолжит диалог и отчитается о результате |
| 📋 Поручения | «Напиши Саше про зарплату», «через час напомни Ане» — из веба или командного бота; агент выберет время и слова, потом отчитается |
| 🎙️ Мультимодальность | Голосовые и видеокружки распознаются офлайн (faster-whisper), фото понимает vision-модель |
| ⚙️ Гибкие настройки | Глобальная инструкция + инструкция на чат, белый/чёрный список, расписание работы, выбор LLM-провайдера и модели |
| 🤖 Командный бот | Управление агентом прямо из Telegram через собственного бота с deep-link привязкой |
| 🔐 Безопасность | Argon2-хэши, подписанные httponly-сессии, CSRF, защита от IDOR, ORM-параметризация, rate-limit, шифрование session-файлов Telethon |
| 🚦 LLM-gateway | Очередь запросов с учётом rate-limit провайдера, ретраи с backoff |
Один процесс, один asyncio-loop.
┌──────────────────────────────────────────────┐
│ python run.py │
└──────────────────────────────────────────────┘
│
┌────────────────┬───────────────────┼───────────────────┬────────────────┐
▼ ▼ ▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌──────────────┐ ┌────────────┐ ┌────────────┐
│ FastAPI │ │ Telegram │ │ Command bot │ │ Scheduler │ │ LLM gateway│
│ web + UI │ │ manager │ │ (Bot API) │ │ (отложенное)│ │ rate-limit │
│ /admin │ │ Telethon │ │ deep-link │ │ follow-ups│ │ retry/backo│
└─────┬─────┘ └─────┬─────┘ └──────┬───────┘ └─────┬──────┘ └─────┬──────┘
│ │ │ │ │
└───────┬───────┴──────────┬───────┴──────────────────┘ │
▼ ▼ ▼
┌──────────────┐ ┌───────────────┐ ┌────────────────────┐
│ SQLAlchemy │ │ agent_engine │◀── tools ───────────▶│ Провайдеры LLM │
│ async SQLite │ │ + agent_tools │ function call │ OpenAI-совместимый │
└──────────────┘ └───────────────┘ │ Anthropic-совмест. │
│ │ └────────────────────┘
┌──────▼───┐ ┌─▼──────────┐
│ Whisper │ │ Vision LLM │
│ (офлайн) │ │ (фото) │
└──────────┘ └──────────┘
Поток агента:
входящее ЛС → приватность-фильтр (лист-режимы, расписание)
→ debounce → сборка контекста (история + стиль владельца)
→ LLM + tools → действие в Telegram → лог события
| Инструмент | Действие |
|---|---|
send_messages |
Ответить в текущем чате (1–3 сообщения, с паузами и «печатает…») |
react |
Поставить эмодзи-реакцию вместо ответа |
mark_read_only |
Прочитать и не отвечать |
do_nothing |
Осознанно проигнорировать (спам, джейлбрейк) |
get_more_history |
Подтянуть больше истории чата |
schedule_followup |
Запланировать собственное сообщение позже |
report_to_owner |
Отчитаться владельцу о достижении цели диалога |
| Инструмент | Действие |
|---|---|
find_contact |
Умный поиск по имени/@username (рус/англ, транслит) |
who_messaged |
Кто недавно писал владельцу |
read_chat |
История чата с id сообщений |
send_to / send_messages |
Отправить сообщения собеседнику |
react |
Реакция на сообщение |
delete_message / edit_message |
Удалить / отредактировать сообщение |
schedule_send |
Отложенная отправка |
add_contact / block_user / unblock_user |
Управление контактами |
my_recent_activity |
Что агент делал сам в последнее время |
set_agent_enabled, set_list_mode, set_chat_in_list, set_chat_agent |
Настройка агента на ходу |
finish_task |
Завершение задачи-поручения с итогом |
Приватность by design: автономному респондеру инструменты чтения чужих чатов и изменения настроек не выдаются — он не может «сливать» контекст других переписок собеседникам.
git clone https://github.com/dreamcatchered/dreamAgent.git
cd dreamAgent
# 1. Зависимости (Python 3.11+)
pip install -r requirements.txt
# 2. Конфигурация
cp .env.example .env
# заполните TG_API_ID/TG_API_HASH (https://my.telegram.org),
# токены LLM-провайдеров, SECRET_KEY, пароль админки
# 3. Старт
python run.pyОткройте:
- Приложение: http://localhost:8000
- Админка: http://localhost:8000/admin
При первом запуске faster-whisper скачает модель (~145 МБ для base);
если она недоступна — приложение работает, голосовые помечаются как нераспознанные.
dreamAgent/
├── run.py # точка входа (web + tg + бот + scheduler)
├── requirements.txt
├── .env.example # шаблон конфигурации
├── agent.svg
└── app/
├── main.py # FastAPI app, lifespan, роутинг страниц
├── config.py # конфиг из .env
├── models.py # ORM-модели (users, accounts, chats, messages, tasks…)
├── database.py # async engine/session
├── security.py # argon2, signed sessions, csrf, rate-limit
├── telegram_manager.py # мульти-аккаунтные Telethon-клиенты
├── agent_engine.py # автоответы, обучение стиля, задачи-поручения
├── agent_tools.py # наборы tools + AgentToolbox (function calling)
├── llm.py # провайдеры: OpenAI- и Anthropic-совместимые, agent loop
├── nvidia_gateway.py # очередь/rate-limit для NIM
├── transcribe.py # faster-whisper (голосовые офлайн)
├── scheduler.py # фоновые задачи
├── llm_log.py # журнал вызовов LLM
├── bot.py # командный бот (deep-link привязка)
├── web/
│ ├── routes_auth.py # регистрация/логин/сессии
│ ├── routes_app.py # аккаунты, чаты, задачи, стили
│ └── routes_admin.py # админка
└── static/ # UI (landing, app, admin)
Все параметры — в .env (шаблон: .env.example). Ключевые группы:
- Web —
HOST,PORT,SECRET_KEY,BASE_URL - Telegram —
TG_API_ID,TG_API_HASH(с my.telegram.org),BOT_TOKEN - LLM — любой OpenAI-совместимый (
NVIDIA_*) или Anthropic-совместимый (OPENMODEL_*) провайдер - Админка —
ADMIN_LOGIN,ADMIN_PASSWORD
.env, БД (data/), медиа и session-файлы не коммитятся — см. .gitignore.
Warning
Этот проект автоматизирует действия от имени вашего собственного Telegram-аккаунта. Используйте его ответственно и законно:
- Не используйте агента для спама, массовых рассылок, скама, манипуляций или введения людей в заблуждение о том, с кем они общаются.
- Автоматизация аккаунтов может нарушать Условия использования Telegram и привести к ограничению аккаунта — вы делаете это на свой риск.
- Собеседники имеют право знать, что общаются с автоматикой; уважайте применимое законодательство о персональных данных.
Автор не несёт ответственности за использование кода третьими лицами. Проект распространяется «как есть» в образовательных целях.