Перейти к основному содержимому

Автоматическое подключение Telegram Agent

Человек пишет задачу в личный чат Bot Builder Agent или обращается к нему в группе. Агент использует Telegram ID отправителя из Update. Существующий профиль сохраняется; новому человеку создаётся пустой профиль без переноса гостевых проектов. Username не является идентификатором. В группах автоматическое подключение принадлежит отправителю сообщения или нажавшему кнопку. ID группы, автор сообщения с кнопкой и ID из текста не определяют доступ. Ответы с данными проектов видны участникам группы. Ручные MCP-подключения сохраняют приоритет.

Настройка​

В конструкторе и агенте задайте одинаковые AGENT_AUTO_AUTH_ID (по умолчанию bot-builder-agent) и AGENT_AUTO_AUTH_SECRET (случайный секрет минимум 32 байта). Ключ хранится только в переменных серверов. В агенте BOT_BUILDER_URL указывает фиксированный HTTPS-адрес конструктора; пользовательские MCP URL не участвуют в обмене. AGENT_AUTO_AUTH_ENABLED=false по умолчанию. В конструкторе AGENT_AUTO_AUTH_ALLOWED_IDS=1612141295 ограничивает первоначальный запуск; пустое значение после проверки разрешает всем пользователям.

Граница доверия: конструктор доверяет удостоверению отправителя сервером агента. Обладатель межсервисного ключа может запросить пользовательский доступ от имени Telegram ID. Ключ нельзя передавать модели, обычным MCP-серверам, в браузер или логи. Клиент обмена запрещает HTTP-редиректы. Браузерная сессия пользователя не заменяется ключом.

Протокол и хранение​

POST /api/auth/agent/telegram возвращает token, expiresAt, connectionId, ownerId. POST /api/auth/agent/disconnect принимает {id} и отключает подключение. Заголовки: X-Agent-Id, X-Agent-Timestamp, X-Agent-Nonce, X-Agent-Signature. Каноническая строка: HTTP-метод, путь, timestamp, nonce, SHA-256 фактических байтов JSON, соединённые LF без завершающего LF. Подпись HMAC-SHA256 в lowercase hex. Timestamp — Unix секунды с допуском 60 секунд; nonce — 16 случайных байт hex. Redis атомарно хранит nonce 120 секунд. Без ключа или Redis обмен закрыт. Лимиты фиксированного окна: 10/мин на пользователя, 300/мин на агента, 20 неправильных подписей/мин на IP. Ответы обмена имеют Cache-Control: no-store.

PAT хранится хешированным в agent_tokens, права read,write, без bot_manager. Срок — 24 часа; агент обновляет его перед использованием, когда осталось меньше 5 минут. Старый PAT действует до своего срока, если подключение не отозвано. Связь agent_connections уникальна по агенту и владельцу. Миграция 0022_agent_connections.sql добавляет необязательную связь PAT с подключением. Агент атомарно сохраняет PAT, срок, тип и MCP-сервер в SQLite на постоянном /data.

Отключение и восстановление​

Во вкладке «Агент» показано состояние и действия «Отключить» / «Подключить снова». GET /api/agent-connections и PATCH /api/agent-connections/{id} доступны только владельцу через браузерную сессию; для изменения требуется совпадающий Origin. Отключение отзывает все связанные PAT. Отзыв одного автоматического PAT через существующий API также отключает подключение. Обычные ручные PAT не затрагиваются. /logout, выключение или удаление автоматического MCP-сервера применяют тот же отзыв. При обрыве сети сохраняется ожидающее отключение и блокируется использование доступа. Следующее сообщение не восстанавливает отозванное подключение: сервер отвечает 403 CONNECTION_REVOKED. Восстановление возможно только явной кнопкой в конструкторе; оно не возвращает силу старым PAT. Новое сообщение после восстановления получает новый PAT. Не повторяйте изменяющий MCP-вызов после неоднозначного обрыва, пока не проверите результат.

Выкатка и откат​

  1. Выпустить миграцию и конструктор с выключенной функцией.
  2. Выпустить агент с выключенной функцией и постоянной SQLite на /data.
  3. Настроить секрет в обоих сервисах, включить обмен только для тестового ID.
  4. Проверить новый и существующий профиль, изоляцию проектов, рестарт, logout и восстановление.
  5. После проверки убрать ограничение ID.

Для отката выключить AGENT_AUTO_AUTH_ENABLED в обоих сервисах; при необходимости отозвать автоматические подключения. Ручные PAT продолжают работать. Полный контракт ошибок и схем генерируется в API. Маршруты обмена не экспортируются в инструменты модели или обычные MCP-клиенты.