Пошаговый план создания AI OS на базе OpenAI Assistants API

AI OS (AI Operating System) – это интеллектуальный ассистент для продуктивности, который помогает ставить цели, планировать день и управлять задачами. Ниже представлен подробный гайд по созданию такой системы с использованием OpenAI Assistants API и стеком Python + Telegram Mini App (веб-приложение внутри Telegram). Гайд разбит на этапы: от архитектуры и настройки ассистента до интеграции с БД и деплоя. Каждая секция содержит необходимые детали, примеры кода и рекомендации.

Архитектура системы AI OS

Компоненты системы:

Telegram Mini App (Frontend) – интерфейс пользователя внутри Telegram. Включает чат-бота и встроенное веб-приложение для взаимодействия (ввод целей/задач, отображение списка задач, план дня и т.д.).
Backend (Python) – веб-сервер (например, FastAPI/Flask), который обрабатывает запросы от Telegram, управляет логикой приложения и общается с внешними сервисами.
OpenAI Assistants API – ядро AI-логики. Отвечает за диалог с пользователем, генерацию плана дня, помощь в коде и прочих интеллектуальных задачах.
База данных Supabase (Postgres) – хранит данные приложении: задачи пользователя, состояния, идентификаторы сессий и т.д.
Платформа деплоя (Railway) – хостинг для бэкенда (контейнер с приложением Python), обеспечивает доступность API для Telegram и пользователей.

Рис. 1: Общая архитектура AI OS. Пользователь взаимодействует с Telegram-ботом (мини-приложением), бот передает запросы на бекенд (развернутый на Railway). Бекенд использует OpenAI Assistants API для «умных» ответов и хранит задачи в базе данных Supabase. Все компоненты связаны через HTTPS API-запросы.

Основной поток работы системы таковpakotinia.medium.com:

Пользователь через интерфейс Telegram отправляет запрос или действие (например, добавить задачу, запрос плана дня).
Telegram-бот/веб-приложение пересылает этот запрос на наш бекенд (HTTP-запросом, например, на webhook или REST API).
Бекенд принимает запрос. В зависимости от типа запроса, он:

Обращается к базе Supabase для сохранения/получения данных (например, добавить новую задачу в таблицу или получить список задач).
Формирует обращение к OpenAI Assistants API – передает сообщение пользователя текущему AI-ассистенту (в контексте соответствующего треда/сессии).

OpenAI (Assistants API) генерирует ответ ассистента (например, текст с планом дня или результат выполнения кода) и возвращает его бекенду.
Бекенд получает ответ, при необходимости пост-обрабатывает (форматирует) его и отправляет обратно в Telegram.
Пользователь получает ответ ассистента (например, подтверждение добавления задачи или расписание на день) прямо в Telegram.

Такая многоуровневая архитектура обеспечивает разделение ответственности: Telegram — только UI, бекенд — бизнес-логика и интеграции, Supabase — хранение данных, OpenAI — интеллект системы.

Настройка AI-ассистента через OpenAI Assistants API

Главная «умная» часть нашего продукта — это AI-ассистент, работающий на базе GPT. OpenAI Assistants API позволяет создать кастомного чат-бота с долговременной памятью, инструментами и встроенными возможностями. Ниже описаны шаги настройки ассистента и примеры кода.

1. Регистрация и ключ API OpenAI

Сначала зарегистрируйтесь на OpenAI платформе и получите API-ключ. Он понадобится бекенду для вызова API. Установите библиотеку OpenAI для Python (pip install openai) и сохраните API-ключ в переменных окружения (например, OPENAI_API_KEY) — не храните ключ в коде для безопасности.

2. Создание ассистента с инструкциями

Assistants API позволяет один раз создать ассистента с заданными настройками (именем, инструкциями, моделью и инструментами). Это как “образ” вашего AI OS. Создадим ассистента программно, задав его поведение.

Пример инструкций ассистента: подумайте, как ассистент должен общаться и что уметь. Например, для AI OS-помощника по продуктивности можно задать на английском или русском:

Копировать кодТы – виртуальный помощник для планирования дня и управления задачами. 
Твоя цель – помогать пользователю ставить цели, планировать расписание и отслеживать выполнение задач. 
Отвечай вежливо и по делу. Если нужно, можешь генерировать короткие фрагменты кода Python для демонстрации идей. 
У тебя есть доступ к списку задач пользователя для составления плана.

Такие инструкции включают роль ассистента (планировщик задач), стиль общения и упоминание функций (например, доступ к задачам, генерация кода). Инструкции будут заданы как системное сообщение и сохранятся в настройках ассистента.

Создание ассистента (HTTP-запросом): на момент написания, OpenAI предоставляет бета-интерфейс Assistants API. Можно вызывать его напрямую через HTTP. Ниже код с использованием requests для создания ассистента:

pythonКопировать кодimport requests
import json

API_KEY = "Ваш_OpenAI_API_KEY"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

assistant_config = {
    "name": "AIPlanner",  # имя ассистента (произвольно)
    "instructions": (
        "You are an AI OS assistant named AIPlanner that helps users manage tasks and plan their day. "
        "Your primary role is to assist with goal setting, daily scheduling, and task tracking. "
        "You can create daily plans using the user's task list, add or remove tasks upon request, "
        "and provide helpful suggestions. "
        "Respond in a clear, friendly manner and use markdown for formatting lists or code."
    ),
    "model": "gpt-4-0613",  # модель, напр. GPT-4
    # "tools": [],  # можно указать инструменты, напр. retrieval или code_interpreter
}
res = requests.post("https://api.openai.com/v1/assistants", headers=headers, json=assistant_config)
data = res.json()
print(data)
assistant_id = data.get("id")

В конфигурации мы задали instructions (описание роли ассистента) и выбрали модель GPT-4. Параметр tools можно использовать для подключения инструментов OpenAI. Например, {"type": "retrieval"} чтобы подключить поисковый индекс по загруженным файламpakotinia.medium.com, или {"type": "code_interpreter"} чтобы ассистент мог выполнять питон-код внутри себяdzone.com. В нашем случае ассистент для продуктивности может обойтись без дополнительных файлов, поэтому tools оставлен пустым.

После успешного вызова мы получим JSON с данными ассистента, включая его id. Сохраните assistant_id – он понадобится для запуска диалогов.

💡 Совет: Вы можете создать ассистента через веб-интерфейс OpenAI (раздел Assistants в личном кабинете) и просто скопировать его ID. Но программная настройка позволяет автоматизировать процесс и гибко менять параметры.

3. Создание треда (Thread) для сеанса общения

Assistants API вводит понятие треда – отдельного диалога/сессии с ассистентом. Каждый тред хранит историю сообщений, то есть контекст беседы сохраняется автоматически. Рекомендуется создавать отдельный тред на каждого пользователя или на каждый независимый разговорdzone.com dzone.com. Это решает проблему памяти в обычных чат-моделях – ассистент будет помнить предыдущие сообщения пользователя без пересылки всего контекста вручную.

Как создать тред: при получении нового запроса от пользователя, если у него еще нет активного треда (например, первый запрос или сброс контекста), нужно создать новый тред. В API это делается вызовом:

pythonКопировать кодthread_res = requests.post("https://api.openai.com/v1/threads", headers=headers)
thread_id = thread_res.json().get("id")

Этот запрос вернет thread_id (строка вида thr-...). В дальнейшем для всех сообщений этого пользователя мы будем использовать один и тот же thread_id чтобы сохранять непрерывность диалога. Можно сохранить соответствие пользователя и его thread_id в базе данных или в памяти приложения.

Контекст на основе thread: Если пользователь закрыл приложение и вернулся позже, мы можем продолжить его разговор, указав тот же thread_id при общении с APIdzone.com. Например, хранить openai_thread_id в таблице пользователей вместе с их Telegram IDn8n.io. В Supabase можно заранее создать таблицу users(telegram_id, openai_thread_id) для этого. Тогда при новом сообщении проверяем, есть ли у пользователя thread_id; если нет – создаем новый тред и сохраняем егоn8n.io.

4. Отправка сообщений пользователя и запуск ассистента

Когда у нас есть ID ассистента и thread_id, можно передать пользовательский запрос в этот тред и получить ответ:

Сначала добавляем сообщение пользователя в тред.
Затем запускаем выполнение треда с указанным ассистентом.
Ожидаем завершения (API асинхронный) и получаем ответное сообщение ассистента.

Пример кода для одного цикла вопрос-ответ:

pythonКопировать кодuser_message = "Привет! Помоги спланировать завтрашний день."
# 1. Отправляем сообщение пользователя в тред
msg_payload = {"role": "user", "content": user_message}
requests.post(f"https://api.openai.com/v1/threads/{thread_id}/messages", 
              headers=headers, json=msg_payload)

# 2. Запускаем ассистента на этом треде
run_payload = {"assistant_id": assistant_id}
run_res = requests.post(f"https://api.openai.com/v1/threads/{thread_id}/runs", 
                        headers=headers, json=run_payload)
run_id = run_res.json().get("id")

# 3. Ожидание завершения (проверяем статус run)
import time
status = "running"
start_time = time.time()
while status not in ["succeeded", "failed"]:
    run_status = requests.get(f"https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}", headers=headers).json()
    status = run_status.get("status")
    if status == "succeeded":
        break
    # задержка перед повторной проверкой
    time.sleep(1)
    # (можно добавить таймаут по времени)

# 4. Получаем все сообщения треда и извлекаем последний ответ ассистента
messages_res = requests.get(f"https://api.openai.com/v1/threads/{thread_id}/messages", headers=headers).json()
messages = messages_res.get("data", [])
assistant_answer = next((m for m in messages[::-1] if m["role"] == "assistant"), {}).get("content")
print("Assistant:", assistant_answer)

В этом примере мы:

Создаем пользовательское сообщение (role: user) с содержимым запроса.
Вызываем runs.create чтобы получить ответ ассистента. Этот вызов асинхронный: сразу вернет run_id, а сам ответ генерируется в фоне.
В цикле опрашиваем runs/{run_id} – как только статус станет "succeeded", прерываем ожиданиеpakotinia.medium.com. (Примечание: OpenAI планирует добавить streaming, тогда можно будет получать ответ сразу по частям без опросаpakotinia.medium.com.)
Получаем список сообщений из треда и вытаскиваем из него последнее сообщение ассистента.

В итоге assistant_answer содержит сгенерированный ответ. Его мы и отправим пользователю через Telegram.

5. Возможности ассистента: инструменты и функции

OpenAI Assistants API предоставляет дополнительные возможности, которые можно задействовать в AI OS:

Retrieval (поиск по знаниям): Ассистент может быть обогащен внешними знаниями. Например, вы можете загрузить документы (PDF, заметки) с целями пользователя или материалами по тайм-менеджменту и подключить их к ассистенту. Интеграция через tools: [{type: "retrieval"}] позволит ассистенту искать релевантные части в загруженных файлах и использовать их для ответаpakotinia.medium.com. OpenAI автоматизирует разбиение документов на фрагменты, создание эмбеддингов и поиск по нимpakotinia.medium.com.
Code Interpreter (выполнение кода): В модели GPT-4 (превью) встроен интерпретатор Python. Это означает, что ассистент сам может решать, когда нужно выполнить код, сгенерировать график или вычислить что-то, и выполнить это за васdzone.com. Для нашего ассистента это полезно, например, для генерирования примеров кода (скриптов), выполнения расчетов по задачам (сумма времени, дедлайны) и т.п. Если в конфиге ассистента включить инструмент {"type": "code_interpreter"}, он сможет при необходимости запускать код (в безопасной песочнице) и использовать результат в ответе.
Function Calling (вызов функций): Новая возможность – ассистент может подсказывать, какую функцию внешнего мира вызвать для выполнения задачиdzone.com. Например, вы можете описать функцию add_task(title, date) и get_tasks(date), и ассистент будет знать, когда нужно вызвать их (вместо того чтобы пытаться сам добавить задачу). Он вернет специальный ответ с именем функции и аргументами, а ваш бекенд выполнит эту функцию (добавит задачу в базу) и вернет результат ассистенту для формирования итогового ответа. В Assistants API функция вызывается не автоматически, но модель сообщает, какую функцию и с какими параметрами нужно вызватьdzone.com. Далее ваш код выполняет функцию и передает результат обратно модели в виде нового сообщения. Это продвинутый сценарий, но очень мощный: с ним AI OS может управлять внешними действиями, не ограничиваясь только текстом. В контексте нашего проекта, через function calling можно реализовать добавление/удаление задач напрямую по команде ассистента.

Указанные возможности можно комбинировать. Например, ассистент может и в базу сходить через функции, и в код что-то просчитать, и в документы посмотреть. Важно не перегружать инструкцию ассистента – формулируйте четко, что ему доступно и чего вы от него ждете.

Примеры промптов для инициализации и задач

Настроив ассистента, важно правильно формировать промпты (запросы), чтобы получить нужный результат. Здесь мы покажем несколько примеров: системное сообщение при инициализации диалога, запросы пользователя на управление задачами и сгенерированные ответы ассистента.

1. Инициализация диалога (system prompt): при создании нового треда вы можете (необязательно) задать начальное системное сообщение, которое уточняет контекст текущего разговора. Например, можно напомнить ассистенту его роль или сообщить текущую дату. В Assistants API роли уже определены инструкциями ассистента, так что дополнительное системное сообщение обычно не требуется. Но можно динамически добавить что-то вроде:

vbnetКопировать кодrole: "system",
content: "Сегодня {дата}. Пользователь хочет спланировать свой день с помощью списка задач."

Это поможет модели знать “сегодняшнюю” дату и тему разговора. Добавлять системные сообщения можно так же через .../threads/{id}/messages перед пользовательскими, с role: "system".

2. Добавление новой задачи:

Пользователь: «Добавь задачу: Позвонить клиенту завтра в 10:00.»
Действия (бекенд): получив эту команду, бэкенд может напрямую внести задачу в базу (Supabase) и затем либо:

Сформировать от себя ответ пользователю (например, “Задача добавлена”), или
Передать запрос ассистенту, чтобы он решил, как ответить. Ассистент, если настроен с функциями, мог бы вернуть function call. Но в простом случае можно передать ассистенту информацию о том, что задача добавлена, и попросить подтвердить.

Ассистент (ответ): «✔️ Готово. Я добавил задачу “Позвонить клиенту” на завтра 10:00 в ваш список.»

В случае прямого вызова, проще сразу отправить пользователю подтверждение. Но если хочется “стилизованный” ответ от AI, можно сделать так: бэкенд добавляет задачу в БД и посылает ассистенту новое системное сообщение: "Новая задача добавлена: Позвонить клиенту (дедлайн: завтра 10:00). Подтверди пользователю." – тогда ассистент сгенерирует подходящий ответ-подтверждение в своём стиле.

3. Запрос списка задач / состояния:

Пользователь: «Какие у меня задачи на сегодня?»
Действия: бэкенд запрашивает из Supabase все задачи пользователя на сегодня и передает их ассистенту (например, как часть запроса). Можно сформировать пользовательский запрос к ассистенту вроде: «Список задач на 12.09.2025: 1) Позвонить клиенту в 10:00 (не выполнена); 2) Написать отчёт до 18:00 (в процессе).» Затем попросить: «Сформируй ответ для пользователя с перечислением задач на сегодня.»
Ассистент (ответ): «Сегодня у вас запланировано:\n• Позвонить клиенту – в 10:00.\n• Написать отчёт – дедлайн сегодня 18:00.\nНе забудьте выделить время на каждую задачу. Успехов!»

Ассистент может сам красиво оформить список задач и добавить совет. Обратите внимание, мы предоставили ассистенту актуальные данные (список задач) — это важно, так как модель не имеет постоянного доступа к нашей БД. Мы встроили данные в запрос. Альтернативно, можно реализовать function calling: ассистенту достаточно знать, что есть функция get_tasks(date=today), он попросит её вызвать, а бэкенд получит список и отправит его обратно. Это сложнее, но избавляет от необходимости всегда вручную формировать подсказку с задачами.

4. Генерация плана на день:

Пользователь: «Составь план на завтра.»
Действия: бэкенд достает задачи на завтра из БД, например 5 задач с разными приоритетами и дедлайнами. Он передает ассистенту запрос: «Задачи на 13.09.2025: 1) Подготовить презентацию (дедлайн 10:00), 2) Встреча с командой (15:00), 3) Отправить отчёт (до конца дня). Составь поминутный план дня, учитывая эти задачи и перерывы.»
Ассистент (ответ): ассистент генерирует структурированный план, например:

markdownКопировать код**План на 13.09.2025 (понедельник):**

- **9:00–10:00** – Завершить подготовку презентации.
- **10:00–10:15** – Короткий перерыв.
- **10:15–11:00** – Просмотреть почту, организационные задачи.
- **11:00–12:30** – Работа над другим проектом.
- **12:30–13:30** – Обед.
- **13:30–14:30** – Финальные правки презентации.
- **15:00–16:00** – Встреча с командой (онлайн).
- **16:00–17:00** – Отправить отчёт и сопроводительное письмо.
- **17:00–18:00** – Резервное время (на случай задержек или дополнительных дел).
- **18:00** – Завершение рабочего дня, планирование следующего дня.

Ассистент распределил задачи по времени и добавил перерывы. Такой ответ отправляется пользователю. Заметьте, в ответе использованы маркдаун-разметка (жирный текст, список) – Telegram умеет отображать это красиво.

5. Генерация кода (по запросу):

AI OS также может помочь в смежных задачах, например, написать полезный скрипт:

Пользователь: «Напиши короткий Python-скрипт, который выводит список моих задач из JSON-файла.»
Ассистент: благодаря встроенным возможностям GPT-4, может сгенерировать код, а с code_interpreter даже протестировать его. Ответ может выглядеть так:

pythonКопировать кодimport json

# Assuming tasks.json is a JSON file with a list of tasks
with open("tasks.json", "r") as f:
    tasks = json.load(f)

for task in tasks:
    title = task.get("title")
    due = task.get("due_date")
    status = task.get("status")
    print(f"- {title} (До: {due}) — Статус: {status}")

Этот скрипт читает задачи из файла tasks.json и печатает их списком.

Ассистент поясняет сгенерированный код. В реальном приложении у нас задачи хранятся в БД, но этот пример показывает, как AI может выходить за рамки простого текста и помогать с автоматизацией через код. Такие возможности делают нашего ассистента похожим на «операционную систему», выполняющую различные пользовательские команды.

Подключение базы данных Supabase и создание таблиц

Для хранения задач, целей и другой информации нам понадобится база данных. Supabase – это облачная платформа, предоставляющая PostgreSQL базу и удобный API. Мы используем Supabase для хранения задач пользователей и, опционально, данных о сессиях (например, thread_id для Assistants API).

Шаги настройки Supabase:

Регистрация и проект: Зарегистрируйтесь на Supabase и создайте новый проект. После создания вы получите URL проекта (например, https://xyzcompany.supabase.co) и API-ключи: публичный (анонимный) и секретный (service role). Публичный ключ можно использовать на клиенте с правилами безопасности, а секретный – на сервере для полного доступа.
Настройка схемы БД: Откройте раздел Table Editor на Supabase или подключитесь любым клиентом к PostgreSQL. Создайте необходимые таблицы. Минимально нужна таблица tasks для задач. Также желательно таблица users для привязки задач к конкретному пользователю и хранения thread_id.

Пример схемы таблиц:

sqlКопировать код-- Таблица пользователей (для хранения openai_thread_id и др. инфо)
create table users (
  id uuid primary key default gen_random_uuid(),
  telegram_id bigint not null unique,
  openai_thread_id text,  -- ID треда Assistants API для контекста
  created_at timestamp with time zone default now()
);

-- Таблица задач
create table tasks (
  id uuid primary key default gen_random_uuid(),
  user_id uuid references users(id) on delete cascade,
  title text not null,
  due_date date,
  status text not null default 'pending',  -- 'pending', 'done', etc.
  created_at timestamp with time zone default now()
);

В этой схеме:

users.telegram_id хранит Telegram ID пользователя (число), чтобы однозначно связывать задачи с конкретным телеграм-аккаунтом. openai_thread_id – строка для ID треда ассистентаn8n.io, чтобы сохранять контекст диалога пользователя.
tasks.user_id ссылается на пользователя. Каждая задача имеет название, необязательную дату выполнения (due_date), статус и временную метку создания.

Можно добавить и другие поля: приоритет, описание, тег проекта и т.д. – по необходимости.

ℹ️ Supabase – это по сути Postgres, поэтому вы можете писать SQL вручную (как выше) или пользоваться GUI. Функция gen_random_uuid() доступна, т.к. Supabase по умолчанию включает расширение pgcrypton8n.io.

Интеграция Supabase в Python: Supabase предоставляет REST API и библиотеки для разных языков. В Python удобно использовать пакет supabase-py. Установите его (pip install supabase_py) и подключитесь:

pythonКопировать кодfrom supabase import create_client

SUPABASE_URL = "https://xyzcompany.supabase.co"
SUPABASE_SERVICE_KEY = "ВАШ_СЕКРЕТНЫЙ_КЛЮЧ"  # service role key для полного доступа

supabase = create_client(SUPABASE_URL, SUPABASE_SERVICE_KEY)

Теперь через объект supabase можно выполнять запросы к таблицам.

Примеры операций с задачами:

Добавление задачи:

pythonКопировать кодnew_task = {
    "user_id": some_user_uuid,
    "title": "Позвонить клиенту",
    "due_date": "2025-09-12"
}
res = supabase.table("tasks").insert(new_task).execute()
if res.get("status_code") == 201:
    print("Task added:", res.get("data"))

Получение задач пользователя (например, на сегодня):

pythonКопировать кодtoday = "2025-09-12"
query = supabase.table("tasks").select("*").eq("user_id", some_user_uuid)
if today:
    query = query.eq("due_date", today)
res = query.execute()
tasks_list = res.get("data", [])

Обновление статуса задачи:

pythonКопировать кодtask_id = "<uuid задачи>"
supabase.table("tasks").update({"status": "done"}).eq("id", task_id).execute()

Удаление задачи:

pythonКопировать кодsupabase.table("tasks").delete().eq("id", task_id).execute()

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

Безопасность доступа: Так как мы вызываем Supabase из бекенда, можно использовать service role key (он дает полный доступ). Этот ключ нельзя публиковать на клиенте, храните его только на сервере (например, в переменной окружения на Railway). Для дополнительной безопасности можно настроить Row Level Security (RLS) в Supabase, чтобы даже при компрометации ключа или использовании публичного ключа, доступ к данным был ограничен владельцем. Например, правило: user_id = auth.uid() – но для этого придется интегрировать Supabase Auth. В нашем случае проще: мы контролируем все запросы через бекенд.

Связь с ассистентом: Бекенд будет использовать БД Supabase каждый раз, когда нужно получить или изменить задачи. Ассистент напрямую к БД не обращается, но он будет получать нужные данные через бекенд (в тексте запроса или вызовом функции). Таким образом, Supabase – надежное хранилище, а бизнес-логика решается в Python-коде.

Интеграция с Telegram Mini App

Теперь, когда у нас есть серверная часть (бекенд с ассистентом и БД), нужно связать ее с интерфейсом в Telegram. Telegram Mini App – это web-приложение, которое может запускаться внутри Telegram (по кнопке из чата с ботом) и выглядеть как нативная часть мессенджера. Также нам понадобится собственно бот, через которого пользователи будут взаимодействовать (открывать мини-апп, получать уведомления и т.д.).

Шаг 1: Создание бота в BotFather

Если еще нет, создайте нового бота через BotFather в Telegram. Просто отправьте команду /newbot и следуйте инструкциям (придумайте имя бота и юзернейм). В результате вы получите токен API вида 123456:ABC-DEF1234ghIkl.... Этот токен нужно сохранить (например, в переменной TELEGRAM_TOKEN бекенда). Через BotFather же можно установить аватар и описание бота.

Шаг 2: Разработка фронтенда (WebApp) для Telegram

Мини-приложение – это обычная веб-страница (HTML/JS), которая загружается внутри Telegram. Вы можете разработать его любым способом (чистый HTML/JS, React, Vue и т.д.). Особенности разработки мини-аппов Telegram:

Telegram предоставляет объект window.Telegram.WebApp в JS, через который можно получать данные о пользователе (имя, user_id и прочее) и взаимодействовать (например, закрыть вебапп, отправить данные боту).
Обязательно подключите скрипт Telegram Web App SDK: <script src="https://telegram.org/js/telegram-web-app.js"></script> в HTML.
Когда мини-апп запущен, Telegram передает query string с параметром tgWebAppData, содержащим зашифрованные данные о пользователе и чате. Необходимо на бекенде проверить подпись этих данных (Telegram присылает хеш) для безопасности. Однако Telegram JS SDK уже предоставляет Telegram.WebApp.initDataUnsafe – распарсенные данные (user id, chat id и пр.). В нашем случае, зная telegram_id пользователя, мы можем соотнести его с записями в БД.

UI функциональность: Ваш веб-приложение может показывать, например, список текущих задач, кнопки для отметки выполненных, форму для добавления новой задачи (название + дата) и кнопку “Сгенерировать план дня”. Также может быть интерфейс чата с AI, но раз у нас AI специализируется на задачах, лучше сделать управляемые кнопки/формы. При этом, сложные запросы (как свободный текст “что мне делать завтра”) можно тоже поддержать, например, отдельным текстовым полем или отправкой через самого бота.

Связь вебаппа с бекендом: Поскольку вебапп – обычная страница, она может делать AJAX-запросы на наш бекенд (который на Railway). Создайте в бекенде необходимые эндпоинты (например, REST API):

GET /tasks?user_id=... – получить список задач (возможно с фильтрами по дате или статусу).
POST /tasks – добавить новую задачу (данные в теле запроса: заголовок, дата, user_id).
PUT /tasks/{id} – обновить задачу (например, пометить выполненной).
DELETE /tasks/{id} – удалить задачу.
POST /assistant – отправить запрос AI-ассистенту (например, в теле: {user_id, message}), в ответ – сгенерированный ассистентом текст.

Вы можете реализовать это на FastAPI: описать схемы данных и функции для каждого маршрута, используя код из предыдущих секций (для работы с Supabase и OpenAI). Убедитесь, что вы проверяете user_id – он должен совпадать с тем, что пришел из Telegram WebApp (чтобы нельзя было запрашивать чужие задачи). Обычно в Telegram.WebApp.initDataUnsafe есть поле user.id – его и используем.

Пример: получение задач через FastAPI

pythonКопировать кодfrom fastapi import FastAPI, HTTPException, Body

app = FastAPI()

@app.get("/tasks")
def get_tasks(user_id: int):
    # В реальности user_id лучше брать из проверенных данных Telegram, а не параметра, во избежание подлога
    user = supabase.table("users").select("*").eq("telegram_id", user_id).execute()
    if not user.get("data"):
        raise HTTPException(status_code=404, detail="User not found")
    user_uuid = user["data"][0]["id"]
    res = supabase.table("tasks").select("*").eq("user_id", user_uuid).execute()
    return res.get("data", [])

@app.post("/tasks")
def create_task(data: dict = Body(...)):
    # ожидаем data = {"telegram_id": ..., "title": ..., "due_date": ...}
    telegram_id = data.get("telegram_id")
    title = data.get("title")
    due_date = data.get("due_date")  # формат "YYYY-MM-DD"
    # найти/создать пользователя
    user_res = supabase.table("users").select("*").eq("telegram_id", telegram_id).execute()
    if not user_res.get("data"):
        # создать нового пользователя и новый thread_id для него
        thread_id = requests.post("https://api.openai.com/v1/threads", headers=headers).json().get("id")
        user_insert = supabase.table("users").insert({
            "telegram_id": telegram_id,
            "openai_thread_id": thread_id
        }).execute()
        user_uuid = user_insert.get("data", [{}])[0].get("id")
    else:
        user_uuid = user_res["data"][0]["id"]
    # добавить задачу
    task = {"user_id": user_uuid, "title": title}
    if due_date:
        task["due_date"] = due_date
    result = supabase.table("tasks").insert(task).execute()
    return result.get("data", [])

Этот упрощенный код показывает логику: при добавлении задачи мы по telegram_id находим пользователя, если нет – создаем запись в users и генерируем для него openai_thread_id (новый тред). Затем вставляем задачу. Аналогично будут реализованы другие методы. Функцию общения с ассистентом (POST /assistant) можно реализовать, приняв сообщение, найдя openai_thread_id пользователя в таблице users и используя код из раздела Assistants API, чтобы получить ответ. После чего вернуть ответ ассистента фронтенду.

Шаг 3: Запуск мини-аппа через бота

Чтобы пользователь открыл ваше веб-приложение, в Telegram-боте должна быть команда или кнопка. Например, сделайте команду /start, которая при первом запуске отправляет приветствие и кнопку «Открыть планировщик». В Bot API есть клавиатура InlineKeyboardButton с параметром web_app для открытия веб-аппа.

Пример на Python с библиотекой python-telegram-bot (PTB):

pythonКопировать кодfrom telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup, WebAppInfo
from telegram.ext import Updater, CommandHandler

def start(update: Update, context):
    keyboard = [
        [InlineKeyboardButton("Открыть планировщик", web_app=WebAppInfo(url="https://<ваш-домен>.railway.app"))]
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    update.message.reply_text("Привет! Я помогу тебе с планированием задач.", reply_markup=reply_markup)

updater = Updater(token=TELEGRAM_TOKEN)
updater.dispatcher.add_handler(CommandHandler("start", start))
updater.start_polling()

Здесь бот при /start пришлет кнопку, которая откроет наш вебапп (URL нужно указать тот, где фронтенд хостится; можно хостить фронтенд на том же Railway как статику, или на Vercel — главное, чтобы был HTTPS). Telegram автоматически передаст контекст пользователя в ваш вебапп.

Альтернативно, можно в BotFather привязать мини-апп к боту (используя спецификацию Domain/Path), тогда пользователи смогут открывать его через профиль бота или команду. Но простой путь — кнопка.

Шаг 4: Получение сообщений и вебхуки

Помимо веб-приложения, полезно, чтобы бот реагировал на текстовые сообщения или команды. Например, пользователь может написать боту «спланируй завтра» прямо в чате. Вы можете настроить бот на прием обычных сообщений и обрабатывать их (похожим на /assistant endpoint образом). Для этого решите, как получать апдейты:

Webhook: В продакшне предпочтительно. Telegram будет отправлять HTTP POST на ваш бекенд при каждом сообщении. Нужно выставить URL вебхука. Развернув бекенд на Railway, вы получите, например, https://yourapp.up.railway.app. Добавьте маршрут для принятия апдейтов, например /webhook и настройте Telegram на него.

Настройка вебхука командой:

bashКопировать кодcurl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" -d "{\"url\": \"https://yourapp.up.railway.app/webhook\"}" -H "Content-Type: application/json"

Этот запрос (можно сделать программно) зарегистрирует вебхук бота на нужный URLgithub.com. После этого входящие сообщения будут идти на ваш бекенд. Вам нужно реализовать обработчик: получить JSON, распознать message.text и chat.id и т.д., и вызывать соответствующие функции (похожие на вышеописанные API).

Polling: Более простой способ для разработки – запускать long-polling (как в примере с PTB выше). Но на Railway постоянно работающий polling-бот может быть прекращен, если контейнер перезапустится. Вебхук надежнее.

Пример обработки вебхука (FastAPI):

pythonКопировать кодfrom fastapi import Request

@app.post("/webhook")
async def telegram_webhook(req: Request):
    data = await req.json()
    # Telegram может присылать update с разными полями (message, callback_query и т.д.)
    if "message" in data:
        chat_id = data["message"]["chat"]["id"]
        text = data["message"].get("text", "")
        user_id = data["message"]["from"]["id"]
        # Обработка команды /start
        if text.startswith("/start"):
            # отправить сообщение с кнопкой вебаппа (как выше)
            send_welcome_with_button(chat_id)
        else:
            # Для прочих сообщений: можно переслать ассистенту
            answer = handle_user_text(user_id, text)
            send_message(chat_id, answer)
    # Telegram требует в ответ 200 OK быстро. Ничего не возвращаем.
    return "ok"

Функции send_welcome_with_button и send_message внутри могут использовать Telegram Bot API (sendMessage метод) для ответа. Можно задействовать requests:

pythonКопировать кодTELEGRAM_TOKEN = "<TOKEN>"
TG_API_URL = f"https://api.telegram.org/bot{TELEGRAM_TOKEN}/sendMessage"

def send_message(chat_id, text):
    payload = {"chat_id": chat_id, "text": text, "parse_mode": "Markdown"}
    requests.post(TG_API_URL, json=payload)

Этого достаточно, чтобы бот отвечал. В handle_user_text вы можете реализовать логику: например, если пользователь пишет свободный текст, направлять его ассистенту и возвращать ответ. Либо реализовать примитивный парсер команд: "добавь ...", "удали ...", но тогда лучше ожидать определенный формат. Удобнее все же, чтобы пользователь взаимодействовал через понятный интерфейс (кнопки, формы вебаппа), а не запоминал команды.

Рис. 2: Пример интерфейса Telegram Mini App для управления задачами (скриншот iTasker). Пользователь видит список задач, может отмечать выполнение, добавлять новые задачи. Подобный веб-интерфейс, встроенный в Telegram, сделает использование AI OS интуитивно понятным.

Примечание: На рис.2 показан реальный бот-планировщик, созданный как мини-приложение (iTasker). Наш проект может иметь похожий UI: список задач с чекбоксами, кнопки фильтрации по дате, а также отдельную кнопку/вкладку «AI Планировщик», где можно запросить совета или план на день от ассистента.

Автоматизация регулярных действий и планирования

Одно из преимуществ AI OS – это возможность автоматизировать рутинные действия. В контексте планировщика задач это означает, что система сама может выполнять некоторые задачи по расписанию или при наступлении определенных условий, без явной команды пользователя. Рассмотрим, что можно автоматизировать и как:

1. Ежедневное утреннее планирование: Пусть ассистент каждое утро формирует для пользователя план дня (на основе задач) и присылает его автоматически в указанное время (например, в 9:00). Для этого на стороне бекенда нужно реализовать расписание (cron-job). Варианты решения:

Использовать встроенный планировщик, например, библиотеку schedule или APScheduler. Он может работать в фоне приложения и запускать функцию каждый день в заданное время.
Использовать внешние средства: Railway пока напрямую крон-задачи не предоставляет, но можно, например, сделать отдельный Endpoint и дергать его через внешнюю cron-службу (или GitHub Actions, но это избыточно). Проще – первый вариант.

Пример с APScheduler (в FastAPI):

pythonКопировать кодfrom apscheduler.schedulers.background import BackgroundScheduler
from datetime import datetime

scheduler = BackgroundScheduler()

def morning_plan_job():
    # Получить всех пользователей (из БД) 
    users = supabase.table("users").select("telegram_id, openai_thread_id").execute().get("data", [])
    for user in users:
        tid = user["telegram_id"]
        thread = user["openai_thread_id"]
        # Получить задачи на сегодня
        today = datetime.utcnow().date().isoformat()
        tasks = supabase.table("tasks").select("title, due_date, status").eq("user_id", user["id"]).eq("due_date", today).execute().get("data", [])
        # Сформировать запрос к ассистенту
        task_list_text = ", ".join([t["title"] for t in tasks]) if tasks else "нет запланированных задач"
        prompt = f"Сегодня {today}. У пользователя запланировано: {task_list_text}. Составь оптимальный распорядок дня."
        # Отправить запрос ассистенту (через API, как раньше)
        answer = ask_assistant(thread_id=thread, message=prompt)
        # Отправить ответ пользователю сообщением
        send_message(chat_id=tid, text=answer)
scheduler.add_job(morning_plan_job, 'cron', hour=9, minute=0)
scheduler.start()

В этом коде мы проходим по всем пользователям каждое утро и генерируем для каждого план. Это может быть ресурсоемко, если много пользователей и GPT-модель дорогая. Для оптимизации можно:

Генерировать план по запросу пользователя (но тут цель – автоматизация без запроса).
Кешировать результаты для пользователей, у которых мало что меняется.
Выбирать только активных пользователей (например, хранить настройку «автоплан утром»).

Но в целом идея ясна: использовать ассистента по крону. Telegram-бот с помощью sendMessage API доставляет результатn8n.io.

2. Напоминания о задачах: Можно настроить оповещения за некоторое время до дедлайна задачи. Например, задача на 15:00 – в 14:45 бот сам напишет: “🔔 Напоминание: через 15 минут Встреча с командой”. Для этого можно при добавлении задачи планировать задачу в APScheduler: scheduler.add_job(func, 'date', run_date=due_datetime - timedelta(minutes=15)). Функция func будет отправлять напоминание. Нужно хранить job_id, чтобы отменять, если задача удалена.

3. Еженедельный отчёт или обзор: Ассистент может по расписанию (например, вечером в пятницу) присылать сводку: сколько задач выполнено за неделю, какие цели достигнуты, что перенеслось. Для этого также планируем cron-задачу, которая собирает данные (считает статусы задач) и генерирует текст через ассистента: «На этой неделе вы выполнили X задач из Y. Отличная работа! Невыполненные задачи: ...».

4. Перенос невыполненных задач: Автоматически каждое утро ассистент мог бы переносить вчерашние незавершенные задачи на сегодня и уведомлять пользователя. Здесь лучше сочетать логику кода и AI: код находит задачи со статусом "pending" с прошедшей датой, обновляет их due_date на сегодня, а ассистент генерирует сообщение: «Я перенес 2 невыполненные задачи со вчера на сегодня.»

5. Автозапуск мини-аппа: Telegram не поддерживает автоматическое открытие вебаппа, но бот может прислать клавиатуру – пользователь все равно должен нажать. Однако, бот может проактивно прислать что-то интересное (как в пунктах выше), стимулируя вовлечение.

При реализации автоматизации, обратите внимание:

Часовой пояс: В Telegram API все времена UNIX-метками (UTC). Если планирование завязано на локальное время пользователя, нужно учитывать часовой пояс. Telegram WebApp передает user.language_code и можно попытаться определить часовой пояс по нему или спросить у пользователя. Проще – планировать по UTC или попросить пользователя указать свой часовой пояс в настройках.
Масштабируемость cron: Если приложение развернуто в нескольких экземплярах, все они начнут дублировать cron-задачи. Это нужно предусмотреть. Одно решение – вынести задачи в отдельный сервис или запускать их только на одном экземпляре (на Railway можно ограничиться одним при стандартном плане). Или использовать распределенный фоновой планировщик (например, через БД: один из экземпляров “выбирается” лидером и выполняет задачи).
Уведомления vs. диалоги: Старайтесь, чтобы автоматические сообщения были информативными, но не слишком частыми, чтобы не раздражать. Хорошо, если они кастомизируются (пользователь может в настройках отключить ежедневный план, например).

Деплой на Railway

После разработки и тестирования локально, вы готовы развернуть AI OS в облаке. Railway – платформа, позволяющая легко деплоить веб-приложения. Вот шаги деплоя:

Подготовка репозитория: Убедитесь, что весь код (бекенд, фронтенд) находится в репозитории (GitHub, GitLab и т.п.). В корне проекта может быть файл requirements.txt или Pipfile для Python-зависимостей. Если фронтенд — статичный (HTML/CSS/JS), положите его файлы, или используйте отдельный сервис (но можно и через Python раздавать).
Railway проект: Зарегистрируйтесь на Railway.app и создайте новый проект. Можно выбрать привязку к GitHub-репо. Railway сам определит тип проекта (например, Python/FastAPI) и предложит команду запуска. Обычно, если обнаружит Procfile или if it's a recognized framework. Если нет, укажите команду вручную. Для Uvicorn/FastAPI это: uvicorn main:app --host 0.0.0.0 --port $PORT.
Добавление переменных окружения: В настройках Railway проекта добавьте ENV VARs:Эти переменные будут доступны в коде (например, через os.getenv).

OPENAI_API_KEY – ключ OpenAI.
SUPABASE_URL и SUPABASE_SERVICE_KEY – данные Supabase.
TELEGRAM_TOKEN – токен бота.
(Возможно, другие: например, если фронт вынесен – URL фронта, SECRET для проверки хеша Telegram WebApp.)

Билд и деплой: После настройки Railway запустит сборку контейнера. Он скачает зависимости и поднимет сервер. Убедитесь, что приложение слушает порт из переменной окружения (в FastAPI uvicorn мы указали --port $PORT). По завершении деплоя Railway выдаст ваш домен, например: https://your-app.up.railway.app.
Настройка вебхуков: Если используете Telegram webhook, теперь выполните запрос setWebhook, как описано ранее, подставив ваш Railway URL + путь вебхука. Например:bashКопировать кодcurl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" -d "{\"url\": \"https://your-app.up.railway.app/webhook\"}" -H "Content-Type: application/json" Убедитесь, что ваш бекенд роут /webhook доступен без авторизации и корректно обрабатывает входящие данные.
Проверка: Откройте диалог с ботом в Telegram, отправьте /start. Бот должен ответить приветствием с кнопкой. Нажмите кнопку – должен загрузиться ваш мини-апп. Попробуйте добавить задачу, сгенерировать план – следите по логам Railway (в Railway есть веб-консоль логов) на ошибки. Также можно подключить мониторинг или отправку ошибок в Sentry для продакшна.

Статичные файлы (фронтенд): Если ваш фронт – просто HTML/CSS, вы можете раздавать их через тот же FastAPI (например, с помощью StaticFiles). Если это React/Vue, задеплойте его либо на Vercel/Netlify и в боте используйте ссылку на тот хост, либо настроить Railway как FullStack (но проще раздельно). В нашем случае, например, вебапп можно деплоить на Vercel и в BotFather указать домен Vercel в настройках Web App. Однако, чтобы упростить, можно и на Railway, поставив Nginx или используя Starlette StaticFiles.

Масштабирование на Railway: На бесплатном плане Railway контейнер спит при простое. Для бота это плохо – вебхук может не достучаться. Поэтому лучше хотя бы базовый платный план, либо использовать трюк: периодически посылать самому себе запрос, чтобы не заснуть. Но надежнее – включить план с постоянным uptime. При росте нагрузки Railway позволяет увеличить план (ресурсы) или добавить еще инстансы (вручную через DUPLICATE deployment или используя их Docker images on other platforms for load balancing). Для начала достаточно одного экземпляра.

Хранение данных: Мы вынесли всё в Supabase, так что бекенд сам по себе без-состояния (стейт только в БД). Это значит, что при перезапусках или множественных инстансах проблем не будет – все читают/пишут одну базу. OpenAI Assistants API тоже внешний сервис. Так что деплой и будущие обновления сводятся к перезаливу нового кода.

Визуальные компоненты (UI и примеры)

(Примеры изображений интерфейса и схемы уже были приведены выше: см. Рис.1 для архитектуры и Рис.2 для UI).

В процессе разработки старайтесь визуализировать логику приложения. Полезно составить блок-схему, как пользовательский ввод проходит через систему и во что трансформируется. Мы включили схему архитектуры (рис.1), показывающую все компоненты и их взаимодействие. Такая схема поможет вам и команде быстро понимать, где какая часть находится и как данные текут.

С точки зрения UI, прототипируйте внешний вид мини-аппа. Рис.2 показывает минималистичный дизайн: список задач с чекбоксами статуса, кнопки «Добавить», выпадающий календарь для фильтра по дате. Ваш UI может быть и еще проще — даже просто чат-окно. Но для продуктивности лучше сочетание: структурированный список + возможность запросить совет. Сделайте интерфейс коротким и ясным: пользователь не должен думать, что ввести. Кнопки «Показать задачи на сегодня», «Запланировать мой день», «Добавить новую задачу» упростят взаимодействие.

Если есть возможность, проведите тестирование UI с парой человек: насколько понятно, каких реакций ожидают от ассистента. Возможно, нужно будет подправить тексты ответов или добавить подсказки.

Советы по развитию проекта

Создание AI OS-планировщика – лишь начало. Вот идеи, как можно улучшать и развивать проект в будущем:

Дополнительные интеграции: Расширьте возможности, подключив календари (Google Calendar, Outlook) – чтобы ассистент мог учитывать встречи из календаря или добавлять события. Также почтовые напоминания или интеграция с таск-трекерами (Trello, Asana) могут сделать проект привлекательнее для командной работы.
Голосовое управление: Telegram поддерживает голосовые сообщения. Добавив конвертацию речи в текст (через сервис, например Whisper API), пользователь сможет голосом добавлять задачи или спрашивать план. А ответы ассистента можно озвучивать обратно (Text-to-Speech) – получится полноценный голосовой помощник.
Многоязычность: Сейчас мы писали на русском. Стоит сделать ассистента билингвальным – хотя бы русский/английский, чтобы охватить больше аудитории. OpenAI отлично справляется с разными языками. Можно определять язык пользователя (есть language_code в Telegram) и подстраивать ответы.
Настройка и обучение ассистента: OpenAI Assistants API позволяет обновлять знания ассистента. Вы можете добавить возможность, чтобы пользователь загружал свои материалы (например, список целей, заметки), а ассистент включал их в контекст (через retrieval). Это сделает ответы более персонализированными и ценными.
Файнтюнинг модели: OpenAI позволяет делать финетюнинг (пока GPT-3.5). Теоретически, можно собрать данные диалогов вашего ассистента с пользователями и дообучить модель под ваш стиль и задачи. Однако, с выходом Assistants API, возможно, проще управлять инструкциями и примерами (few-shot) вместо полноценного обучения.
Улучшение UX мини-аппа: Используйте возможности Telegram WebApp – они поддерживают красивую анимацию открытия, гибкую компоновку. Добавьте индикацию работы (когда ассистент думает – показывайте “AI typing…” или спиннер). Реализуйте локальное сохранение черновиков задач, если сеть пропала.
Масштабирование для команд: Сейчас планировщик индивидуальный. Рассмотрите функционал для команд/групп: например, общий проект с задачами, где ассистент напоминает всей группе о дедлайнах, распределяет задачи между людьми на основе их загрузки (интересный AI-задачник!). Telegram позволяет ботов в группах – можно сделать, чтобы ассистент умел отвечать в групповом чате на запрос типа “@YourBot что по задачам на сегодня?”.
Монетизация и ограничения: Если планируете публиковать проект широко, подумайте о модели монетизации. Например, бесплатный тариф – ограниченный функционал или ограниченное число запросов к AI в день, а платный – безлимитный и с приоритетом. Реализовать это можно хранением поля is_premium в users и проверкой перед вызовом OpenAI (как советует OpenAI – они даже позволяют метаданные thread хранить, например, premium статусdzone.com). Боту можно научить отвечать, что, мол, “эта функция доступна в премиум версии”.
Обратная связь и дообучение: Собирайте фидбек от пользователей. Можно встроить команду /feedback, чтобы пользователь отправил, что ассистент спланировал плохо. Эти данные помогут вам вручную анализировать, где модель ошибается или дает неудобные планы, и корректировать инструкции или логику (например, всегда спрашивать у пользователя предпочтения по времени отдыха и т.д.).
Обновление технологий: Следите за обновлениями OpenAI. Возможно, появятся новые модели, более дешевые или быстрые, которые можно использовать. Или Assistants API выйдет из беты с улучшенными функциями (например, стриминг ответов, чтобы не ждать конца ответа, а отправлять частями в Telegram). Supabase тоже развивается – можно использовать их Edge Functions вместо части бекенда (например, хранить логику добавления задач прямо в Supabase функциях – но это уже на любителя, наш Python-код вполне справляется).

Развивая проект, всегда держите в центре пользователя и его удобство. AI OS должен облегчать жизнь, а не усложнять. Каждое новое фича проверяйте: делает ли оно планирование еще проще и эффективнее? Если да – вперед. И не забывайте про сообщество: идеи улучшения можно черпать из опыта других (форумы, блоги). Например, шаблоны промптов для продуктивности, лучшие практики по тайм-менеджменту – их можно «встроить» в ассистента, чтобы он давал действительно ценные советы, а не просто перерабатывал задачи.

Поздравляем, теперь у вас есть дорожная карта для создания собственного AI-планировщика! Такой проект сочетает в себе возможности современных LLM (больших языковых моделей) и классические инструменты разработки веб-приложений. Следуя этому гайду, вы создадите мощное приложение, которое будет не просто списком задач, а настоящим умным ассистентом, помогающим пользователям достигать целей каждый день. Успехов в разработке!