Сначала договорись, где живёт каждое поле
Интеграция AI ломается не на вызове модели, а на вопросе «какое поле теперь считается правильным?». Если CRM, календарь и таблица спорят, новая связка только ускорит путаницу.
Первое, что я бы убрал: Выдавать интеграции полный доступ к системе, потому что так быстрее подключить демо.
Что проверить до подключения систем
- Источник истины для каждого поля.
- Разрешённые чтение и запись.
- ID события и защита от повтора.
- Тест ошибки внешней системы и ручной откат.
Как связать AI с файлами и сервисами
- Опиши владельца каждого поля
В таблице интеграции укажи: поле, система-владелец, формат, направление, кто может менять и что делать при конфликте.
Что увидишь: Нет двух систем, которые считают себя владельцем одного значения.
Если не сработало: Оставь поле только для чтения в одной системе.
- Выдай минимальные credentials
Создай отдельные ключи или OAuth-доступы для workflow. Где возможно, используй read-only и ограничь папку, проект или таблицу.
Сверь: Отзыв одного ключа не ломает весь бизнес и не открывает лишние данные.
Если не сходится: Сначала протестируй на sandbox-аккаунте.
- Сделай transform явным
Перед AI и записью нормализуй даты, телефоны, enum и вложенные JSON. Не передавай целый объект, если нужны три поля.
Что должно совпасть: Одинаковый вход даёт одинаковый формат target.
Если ответ другой: Добавь validation step и пример ожидаемого JSON.
- Добавь идемпотентность и ошибки
Храни event_id, ограничь число повторов и создай dead-letter очередь для случаев, которые требуют человека.
Перед запуском: Повтор не создаёт дубль, а ошибка видна владельцу.
Если упёрлось: Останови workflow после одного контролируемого повтора и уведоми команду.
Карта полей до подключения
Сделай таблицу event_name, source_system, target_system, source_field, target_field, transform, required, owner и failure_route. Например: form.email → crm.email, normalize_phone → crm.phone, form.request → crm.note. Поле без владельца лучше не переносить автоматически.
Сначала запиши событие в журнал, затем нормализуй данные, проверь обязательные поля и только потом вызывай Create/Update. Для каждого запуска храни source_event_id и target_record_id.
- Тестируй пустое поле, повторный webhook и недоступный API.
- Не выдавай интеграции права на удаление, если ей нужен только create/update.
Как искать ошибку за пять минут
Открой run log и проверь цепочку: событие получено, данные распарсились, правило прошло, API ответил, target_record_id сохранён. Если есть только итоговая ошибка без входа и ответа API, логирование настроено слишком поздно.
Тестирую повторную доставку и недоступную CRM
Отправь один и тот же webhook дважды, затем отключи CRM перед шагом Create/Update. Правильный результат: второй запуск находит `source_event_id`, а сбой сохраняет вход, ответ API, retry_count и срок следующей попытки. Если повторить безопасно нельзя, останови интеграцию до выдачи боевых прав.
Сделай отдельный маршрут `failed → retryable → retried/needs_human`. Для каждого запуска сохраняй `target_record_id` только после подтверждённого ответа CRM. Так видно разницу: «запись не создана» и «запись создана, но ответ потерялся».
Какие действия разрешить модели
| Критерий | Вопрос | Хороший признак |
|---|---|---|
| Вход | Что подготовить для связь AI с бизнес-системами? | Нарисуй карту event → source → transform → target → owner и укажи для каждого поля направление, формат и право записи. |
| Действие | Что система может сделать сама? | Только заранее перечисленные действия, без доступа ко всему аккаунту |
| Проверка | Как понять, что результат можно принять? | Проверь повтор webhook, пропущенное поле, истёкший токен, таймаут и ответ API с неожиданной структурой. |
| Сбой | Куда уходит непонятный случай? | Сохрани событие в очередь повторной обработки с run_id и причиной сбоя; не запускай бесконечные ретраи. |
Как выглядит проверяемая интеграция
Связка файлов, CRM, календаря и почты получает понятные границы. При сбое видно вход, действие и место, где результат передали человеку.
Где связка дублирует данные
Подключать сервисы без карты владения данными.
Использовать один глобальный ключ с правами администратора.
Доверять разным форматам дат и enum.
Считать успешным запуск, который просто не показал ошибку.
Когда нужна отдельная архитектура
Если интеграция касается денег, персональных данных или большого числа событий, проектируй права, повторную обработку и идемпотентность до выбора ноды.
Что проверить после первого webhook
Кому подходит связь AI с бизнес-системами?
До кнопки Connect реши: какое событие переносит какие поля, кто владеет данными и что происходит при повторе или ошибке.
С чего начать, если всё пока вручную?
Для первого шага нарисуй карту event → source → transform → target → owner и укажи для каждого поля направление, формат и право записи.
Как проверить, что настройка не навредит?
Проверка здесь такая: проверь повтор webhook, пропущенное поле, истёкший токен, таймаут и ответ API с неожиданной структурой.
Что делать при непонятном результате?
При таком результате сохрани событие в очередь повторной обработки с run_id и причиной сбоя; не запускай бесконечные ретраи.
