Встречи и Google Календарь

Календарь позволяет AI-агенту превратить разговор в настоящую встречу. Настраивается он в разделе AI → Календарь, а агент пользуется им через четыре инструмента: показать свободные слоты, записать, перенести, отменить.

Сейчас доступен провайдер Google Календарь. Сама платформа написана поверх провайдеро-независимого интерфейса, поэтому типы встреч, записи и инструменты агента не зависят от особенностей Google.

Подключение аккаунта

Нажмите Подключить Google Календарь. Окно авторизации открывается с одноразовым state, который привязан к боту и вашему аккаунту и живёт пять минут, использует PKCE и возвращается на один точный адрес. Запрашивается доступ только к списку календарей, событиям и сведениям о занятости.

Refresh-токен хранится зашифрованным и больше не показывается. На карточке подключения видны только метка аккаунта и одно из четырёх состояний: Подключён, Доступ истёк, Отключён, Ошибка. Если доступ истёк, подключите аккаунт заново.

Кнопка Отключить календарь заблокирована, пока у активного агента включены календарные инструменты – интерфейс перечислит таких агентов. Сначала уберите инструменты или поставьте агента на паузу.

Типы встреч

Тип встречи – это то, что агент реально предлагает. В нём задаются:

  • Название – видно вам в отчётах и клиенту в событии.
  • Календарь из подключённого аккаунта. Сохранённый идентификатор календаря шифруется и больше не отображается, поэтому при редактировании типа встречи календарь выбирается заново.
  • Длительность – от 5 до 480 минут.
  • Часовой пояс – имя из базы IANA, например Europe/Berlin. Он задаёт, что означает доступное время ниже.
  • Доступное время – от 1 до 28 недельных интервалов с границами вида ЧЧ:ММ по дням недели. Интервалы не должны пересекаться; интервал, у которого конец раньше начала, переходит через полночь.
  • Минимальный запас перед встречей – от 0 до 1 440 минут, раньше этого срока записаться нельзя.
  • Насколько вперёд можно записаться – от 1 до 366 дней.
  • Перерыв до и перерыв после – по 0–1 440 минут, остаются свободными вокруг встречи.
  • Тип встречи включён – предлагать и бронировать можно только включённые типы.

Кнопка Показать свободные слоты показывает настоящий результат на ближайшую неделю по подключённому календарю, а не имитацию.

Как выбирается слот

Доступность считается сразу по четырём входам: недельные часы типа встречи, занятые интервалы из календаря, перерывы и уже существующие записи этого подключения. Кандидаты берутся с шагом 15 минут; по умолчанию возвращается 10 слотов и никогда больше 20.

Время показывается в часовом поясе клиента и хранится в UTC, поэтому переход на летнее время сдвигает предлагаемое местное время, а не сохранённый момент.

Запись сделана намеренно осторожно:

  1. Выбранный слот проверяется ещё раз – прямо перед любой записью.
  2. Сохраняется ожидающая бронь с ключом идемпотентности, поэтому повторный запрос не создаст вторую встречу.
  3. В календаре создаётся событие, при необходимости со ссылкой на видеовстречу.
  4. Если провайдер отвалился по таймауту или вернул повторяемую ошибку, бронь сначала ищется по ключу идемпотентности, поэтому неоднозначный таймаут не порождает дубль.
  5. Только после этого бронь подтверждается. Идентификатор события у провайдера и ссылка на встречу хранятся зашифрованными.

Перенос и отмена работают по той же схеме, а бронь, чей слот успел освободиться-занять, завершается ошибкой вместо двойной записи.

Состояния брони: Ожидает, Подтверждена, Перенесена, Отменена, Ошибка.

Как выдать инструменты агенту

В редакторе агента, в блоке Разрешённые инструменты, включите нужные календарные действия:

  • Показывать свободные слоты
  • Записывать на встречу
  • Переносить встречу
  • Отменять встречу

Для каждого включённого календарного инструмента нужно указать хотя бы один актуальный включённый тип встречи – иначе проверка готовности не даст активировать агента. Активный агент может пользоваться только календарными инструментами: другие в бою пока не запускаются.

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

Отчётность

AI → Аналитика показывает календарные действия и итоги записей рядом с остальными метриками агента, а AI → Календарь – сами брони.

Что делать, если

  • Включены календарные инструменты, но нет включённого типа встречи – создайте тип или включите существующий до активации агента.
  • Не удалось загрузить список календарей – возможно, аккаунт нужно подключить заново; как временный обходной путь идентификатор подключения можно ввести вручную.
  • Нет свободных слотов на ближайшей неделе – проверьте недельные часы, минимальный запас, перерывы и загруженность календаря.
  • Тип встречи используется и не может быть удалён – на него ссылаются календарные инструменты активного агента.

Связанные материалы