Обратимое создание пользователей SaaS силами ИИ-агентов

ИИ-агент не должен создавать пользователя SaaS по непрозрачной команде вроде «добавь Priya в корпоративную учетную запись с обычным доступом инженера». В ней скрыты как минимум три изменения состояния: создание или приглашение личности, назначение роли на уровне учетной записи и добавление в группы. У каждого изменения свои риск, условие завершения и способ отмены.

Обратимое создание пользователей SaaS начинается с сохранения этих границ. Агент предлагает последовательность, выполняет по одному вызову, записывает возвращенные идентификаторы и останавливается, если наблюдаемое состояние отличается от ожидаемого. Несколько дополнительных вызовов API обходятся дешевле, чем восстановление картины после тайм-аута, ошибочного адреса или слишком широкой группы.

Приглашение, роль и членство имеют разные состояния

Ожидающее приглашение еще не пользователь, пользователь не роль, а роль не членство в группе. Системы часто смешивают эти объекты, потому что консоль поставщика показывает их в одной форме. В API им нередко соответствуют разные ресурсы и операции жизненного цикла. От этого различия зависит безопасное восстановление.

Приглашение обычно выражает намерение и процесс доставки или принятия. Получателю может потребоваться принять его, использовать другую личность или вовсе не ответить. Microsoft Graph прямо описывает это для внешних пользователей: создание возвращает объект приглашения, а человек завершает интерактивный процесс. В GitHub членство в организации тоже остается ожидающим до принятия. Запись «пользователь создан» сразу после приглашения фиксирует надежду, а не факт.

Роль меняет полномочия в учетной записи или организации. Человек может стать владельцем, ответственным за оплату, администратором, гостем или обычным участником. Группа часто косвенно открывает проекты, репозитории, каналы, приложения или общие данные. Удаление из группы может закрыть этот доступ без смены роли, а понижение роли может сохранить права от групп.

Моделируйте состояния отдельно, даже если поставщик принимает их одним POST. Разумная внутренняя запись выглядит так:

{
  "subject": "[email protected]",
  "invitation": {"state": "pending", "id": "inv_8421"},
  "role": {"desired": "member", "observed": null},
  "groups": {
    "desired": ["engineering", "on-call-readers"],
    "observed": []
  }
}

Разделение отвечает на неудобный вопрос: что именно отменять? Если приглашение есть, но учетная запись не принята, отмените приглашение. При неверной роли верните прежнюю. Если первая группа добавлена, а следующий вызов не удался, удалите только созданное этим запуском членство. Удалять всего пользователя вместо выяснения изменившегося состояния обычно безрассудно.

Первая норма проста: одно действие журнала должно соответствовать одному наблюдаемому переходу удаленного состояния. Вызов может отправить письмо, но агент и оператор должны уметь назвать основное изменение без добавления «а еще он…».

План должен состоять из данных, а не из прозы

До обращения к поставщику агент должен преобразовать человеческий запрос в типизированный план. Он выводит неоднозначные допущения наружу и дает исполнителю стабильные входные данные. Свободные рассуждения заканчиваются до исполнения; на его границу поступают скучные и точные данные.

Плану нужны субъект, целевой арендатор, способ приглашения, требуемая роль и группы, предусловия и идентификатор операции. Также в нем явно указывают разрешение на отправку письма. Доставку нельзя отозвать отменой приглашения, поэтому скрывать ее за значением по умолчанию нельзя.

{
  "operation_id": "prov_2026_07_24_0187",
  "tenant": "acme-production",
  "subject": {"email": "[email protected]"},
  "steps": [
    {"kind": "invite", "send_email": false},
    {"kind": "wait_for_acceptance"},
    {"kind": "set_role", "role": "member"},
    {"kind": "add_group", "group": "engineering"},
    {"kind": "add_group", "group": "on-call-readers"}
  ],
  "preconditions": {
    "account_absent": true,
    "allowed_email_domain": "example.test"
  }
}

Оставляйте каждую группу отдельным шагом, а не передавайте массив широкому endpoint. Тогда исполнитель отдельно одобряет, повторяет и компенсирует каждое членство. Видим и порядок: если роль можно назначить только после принятия, wait_for_acceptance становится барьером состояния, а не задержкой по таймеру.

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

Предварительные чтения фиксируют существующее состояние. Ищите субъект по документированному уникальному атрибуту, затем читайте прямую роль и членства. «Не найдено» не равно «чтение не удалось». Ошибка 403, тайм-аут или неполная страница не доказывают отсутствия. При eventual consistency или пагинации перед созданием нужна более строгая проверка.

После одобрения заморозьте план. Изменение адреса, роли, ID группы или флага доставки требует нового ID операции и нового решения. Иначе одобренная формулировка незаметно разойдется с фактическими вызовами.

Сначала подготовьте приглашение, потом выдавайте доступ

Сначала создайте или отправьте приглашение и остановитесь, пока сервис не подтвердит результат. Не вкладывайте привилегированную роль и чувствительные группы только потому, что endpoint позволяет. Объединение кажется эффективным: один запрос выглядит атомарным и отправляет одно уведомление. Большинство SaaS API не обещает транзакцию между личностью, ролью, письмом и распространением групп.

Endpoint приглашений GitHub показывает соблазн: запрос может содержать роль и ID команд. Для владельца в консоли это удобно, но автономный исполнитель теряет контрольные точки. Ошибка проверки может отвергнуть всё, а потерянный ответ оставит неизвестными примененные эффекты. Человек также может принять приглашение гораздо позже и активировать доступ после завершения запуска.

Выбирайте приглашение с минимальными полномочиями. Если роль обязательна, используйте обычного участника, а повышение отложите. Если нужна группа или канал, выберите площадку прибытия без чувствительных ресурсов. Например, метод Slack Enterprise Grid требует хотя бы один канал. Это повод создать малопривилегированный входной канал, а не добавлять все рабочие каналы сразу.

Запишите факт отправки письма, ID, статус, время и канонический субъект из ответа. Не помещайте ссылку принятия в широкий журнал: она может работать как bearer-право. Передавайте ее через минимальный доверенный компонент и скрывайте от результатов агента.

У приглашения должно быть явное конечное состояние. Используйте accepted, expired, cancelled и pending, если они доступны. Иначе выводите состояние из документированных полей и отмечайте его как производное. Ответ 201 на POST не означает доступа к производственным данным.

Задайте срок в локальной операции. После его истечения прочитайте состояние и отмените еще ожидающее приглашение, если запрос утратил силу. Не отменяйте вслепую: человек мог принять его мгновением раньше. Сначала чтение и сравнение, затем действие.

Отмена обратима лишь в узком смысле. Она может помешать будущему принятию, но не отзывает письмо и не стирает знание об организации. Укажите этот предел на карточке одобрения. «Обратимо» должно описывать удаленную авторизацию, а не обещать исчезновение всех последствий.

Роль назначают после стабилизации личности

Дождитесь привязки запроса к стабильному удаленному ID пользователя. Email удобен для поиска, но плох как постоянный ключ: адреса меняются, псевдонимы конфликтуют, а приглашение может быть принято существующей учетной записью. Следующие вызовы должны использовать ID поставщика.

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

Отделяйте повышение полномочий от обычного членства. Стандартную роль можно назначать по одобрению сессии, а владелец, администратор и платежные полномочия требуют решения на каждый вызов. Граница следует за последствием использования ключа, а не за HTTP-методом. PATCH /users/123 может быть обычным или опасным из-за одного поля.

Используйте условную запись: ETag с If-Match, поле версии или ревизию поставщика. Она мешает стереть человеческое изменение после предварительного чтения. При конфликте прочитайте снова и остановитесь. Не принуждайте старый план: конкурентная правка может быть важнейшим фактом.

Запись роли содержит прежнее, запрошенное и наблюдаемое значение, удаленный ID, статус ответа и версию, но не bearer-токен:

{
  "operation_id": "prov_2026_07_24_0187",
  "step": 3,
  "action": "role.set",
  "subject_id": "usr_1938",
  "before": "guest",
  "requested": "member",
  "observed": "member",
  "http_status": 200,
  "undo": {"action": "role.set", "value": "guest"}
}

Успешный ответ обновления еще не завершает смену роли. Перечитайте ресурс и подтвердите эффективное значение. API может вернуть 202 Accepted, применить изменение асинхронно или разделить ожидающую и активную записи. До чтения журнал показывает requested, а не observed.

Если компенсация понижает роль, решите, требуется ли отдельное одобрение. Вернуть guest после случайного владельца часто безопаснее ожидания, но автоматическая отмена может противоречить человеческому исправлению. Разрешайте ее, только пока версия совпадает с созданной этой операцией; иначе покажите расхождение.

Каждую группу добавляют отдельным вызовом

У каждого членства должны быть собственные шаг, удаленный ID, результат и отмена. В группах часто скрывается широкий доступ. engineering может управлять репозиториями, развертыванием, аварийными каналами и синхронизированными приложениями. По дружелюбному имени этот охват не определить.

Разрешайте группы через каталог вне prompt. Он связывает отображаемое имя с неизменяемым ID арендатора и описывает прямое, вложенное, динамическое или синхронизированное членство. Одинаковые имена приводят к отказу. Если группой управляет правило, не боритесь с ним повторными прямыми записями.

Directory API Google Admin SDK разделяет добавление, обновление и удаление участника через DELETE. Документация предупреждает о задержке вложенного членства и отвергает циклы. Значит, нужно проверять наблюдаемое состояние, а не предполагать мгновенную согласованность.

В примере PATCH RFC 7644 для SCIM добавление уже существующего участника не должно менять ресурс и должно вернуть успех. Это удобно для повторов, но реализации отличаются. Проверьте поставщика и сохраните путь сверки.

Шаг группы различает added, already_present, rejected и unknown. Для already_present нельзя создавать отмену, иначе она удалит прежний доступ. Unknown означает возможный успех при потерянном ответе или проверке. Нужна сверка, а не оптимистичный повтор.

Обрабатывайте группы от меньших полномочий к большим. Сначала обычная совместная работа, затем администрирование производства. Это не устраняет ущерб, но оставляет меньше доступа при остановке. На каждой чувствительной границе запрашивайте новое одобрение.

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

После добавления читайте прямое членство, не плоский эффективный доступ. Эффективное право может идти от родительской группы и сохраниться после удаления прямого ребра. Квитанция должна называть созданное операцией ребро.

Безопасный повтор начинается с наблюдаемого состояния

Политика повторов не делает любой POST безопасным. RFC 9110 определяет PUT, DELETE и безопасные методы как идемпотентные по намеренному эффекту. Неидемпотентный запрос нельзя автоматически повторять без знания его семантики или доказательства, что первый не был применен.

Опасен тайм-аут после отправки приглашения. Сервер мог создать его и отправить письмо до разрыва соединения. Повтор создаст дубликат. Сначала прочитайте по субъекту и арендатору, затем примите найденный объект, повторите лишь при доказанном отсутствии либо остановитесь при неоднозначности.

Используйте документированный ключ идемпотентности. Выведите его из неизменяемого ID операции и номера шага, сохраните и применяйте для той же логической попытки. Новый ключ после тайм-аута сообщает серверу о новом действии.

Без ключа каждому действию записи нужна функция сверки. Она находит объект точно: адрес и арендатор для приглашения, пользователь и группа для ребра. Если точного запроса нет, неопределенный результат требует человека.

У повторов должен быть бюджет. Соблюдайте Retry-After, используйте ограниченную задержку для временных ошибок и останавливайтесь при проверке, запрете или конфликте. Ошибка 403 не медленный 200. Повторные карточки отказа приучают одобрять не читая.

Надежный исполнитель использует таблицу:

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

Откат означает компенсацию, а не возврат времени

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

Стройте стек из подтвержденных изменений, не из плана. Уже существующую группу не удаляют, не примененную роль не возвращают. При неизвестном результате сначала сверяют состояние.

Полезная квитанция ограничивает обратное действие:

{
  "action": "group.add",
  "target": {"user_id": "usr_1938", "group_id": "grp_77"},
  "result": "added",
  "remote_version_after": "W/\"9012\"",
  "compensation": {
    "action": "group.remove",
    "only_if_direct_membership_matches": true
  }
}

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

Не у каждого эффекта есть компенсация. Письмо не отозвать, событие аудита не следует удалять, лицензия может повлиять на счет, а downstream-провайдер может распространить группу позднее. Пометьте остаточные эффекты, а не объявляйте безусловно полный откат.

Откату нужны срок и эскалация. Ключи истекают, сервисы падают, процесс агента завершается. Храните квитанции вне его контекста, чтобы доверенный исполнитель продолжил. Оператор должен видеть rollback_pending, а не мягкую ошибку в стенограмме.

Проверьте компенсации в непроизводственном арендаторе: создайте и отмените приглашение, проверьте ссылку; добавьте и удалите прямое ребро, проверьте эффективный доступ; измените малорисковую роль и верните ее при конфликте. Документация описывает намерение, тест показывает фактическое поведение.

Журнал должен доказывать причину и следствие

Хороший журнал отвечает, кто запросил изменение, какой процесс его выполнил, какая граница ключа разрешила действие, какой удаленный объект изменился и как результат проверили. Стенограммы инструментов мало: рассказ агента может ошибаться, а HTTP-тела бывают чувствительными и большими.

Назначайте стабильные ID операциям и шагам. Храните хеш плана, арендатора, нормализованный субъект, удаленные ID, решение, отпечаток запроса, статус, проверочное чтение и компенсацию. Редактированные фрагменты ответа сохраняйте только для объяснения. Хеш позволяет сравнить ответ без копирования персональных данных.

Отделяйте утверждения от наблюдений. requested_role: member выражает намерение, response_status: 200 наблюдает транспорт, observed_role: member фиксирует проверенное удаленное состояние. Один флаг success уничтожает нужные при инциденте доказательства.

Командная строка должна ясно показывать частичное завершение:

$ provision status prov_2026_07_24_0187
STEP  ACTION                 RESULT            UNDO
1     invitation.create      accepted          unavailable
2     acceptance.wait        observed          n/a
3     role.set               changed           ready: guest
4     group.add engineering  added             ready
5     group.add on-call      denied            none
STATE partial_failure

Здесь видно: учетная запись есть, роль изменилась, одна группа добавлена, последняя запрещена. Результат не сведен к «создание не удалось». Различие помогает и компенсации, и продолжению после исправления полномочий.

Защищайте журнал от действующего агента. Если он переписывает свои доказательства, запись мало значит. Sallyport показывает сессии и отдельные вызовы как два представления одного зашифрованного журнала с хеш-цепочкой; sp audit verify проверяет цепочку по шифротексту офлайн и без ключа. Это не заменяет журналы поставщика, но дает независимую локальную последовательность.

Связывайте локальные ID шагов с ID запросов поставщика. Поддержка найдет серверные трассы, а локальная запись объяснит намерение и одобрение. Сохраняйте время, но упорядочивайте по монотонной локальной последовательности, поскольку часы и асинхронные события расходятся.

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

Одобрение ставят на границе последствий

Человек принимает хорошее решение, когда карточка описывает одно последствие. «Разрешить создание» слишком широко. «Пригласить [email protected] в acme-production без письма» проверяемо. Изменение usr_1938 с guest на member и добавление в production-deployers заслуживают отдельных решений при разном риске.

Показывайте разрешенные ID и текущее состояние, а не только слова агента. Нужны арендатор, канонический субъект, действие, значения до и после, доступная компенсация. Для приглашения укажите отправку письма, для группы покажите неизменяемый ID рядом с именем.

Одобрение сессии подходит повторяющимся малорисковым вызовам, а чувствительный ключ требует решения при каждом использовании. Фиксированная лестница Sallyport это разделяет: хранилище должно быть открыто, новый процесс по умолчанию получает разрешение сессии, а флаг ключа может требовать одобрения каждого вызова. Привилегированный ключ следует поставить за строгую границу, а не просить модель сдерживать себя.

Одобрение не исправляет слабое исполнение. Человек может выбрать верную группу и получить дублирующий POST после тайм-аута. За идемпотентность, проверку и компенсацию отвечает исполнитель. Идеальный журнал также не делает чрезмерно мощный ключ безопасным.

Убирайте карточки без решения. Ограниченные чтения могут входить в сессию. Точный пустой шаг записывается без «одобрения» несуществующего изменения. Объединяйте одинаковые малорисковые членства только если интерфейс показывает все цели, а механизм хранит отдельные квитанции.

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

Неудачный запуск должен оставаться понятным

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

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

Удалять пользователя нельзя: можно потерять данные, сломать уже принятую личность или столкнуться с последующими системами. Нельзя повторять 403, обещать отмену доставленного письма или подменять запрещенную группу более широкой.

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

Подход работает и при увольнении. Отзыв сессий, удаление групп, смена роли, блокировка и удаление имеют разную срочность и обратимость. Назначение лицензии остается отдельным, если API отделяет его от группы. Правило одно: сохранять значимые границы удаленного состояния в плане и доказательствах.

Дополнительные вызовы создают намеренное трение. На этих точках можно проверить личность, ограничить полномочия, остановиться при расхождении и отменить лишь изменения этой операции. Автономный агент заслуживает больше свободы, когда его работу можно проверить на таких границах. Если API объединяет последствия в один необратимый вызов, честно пометьте его и поставьте перед ним человека.