теория
Шлюз опубликован — и в ту же секунду начал стареть: партнёры попросят поля, тендеры изменятся, каталог перекроится. Добро пожаловать обратно в десятый модуль — с одной новой и неприятной деталью.
Правила эволюции те же, слово в слово. Только добавляй: новые инструменты и необязательные параметры — можно; переименовывать и удалять — нельзя; менять смысл существующего — тем более. Терпимый читатель — уже на нашей стороне шлюза: незнакомые поля в запросах партнёров игнорировать, а не падать. Терпимость — к незнакомым полям; к содержимому знакомых — паранойя, о ней ниже. Реестр схем: каждая версия инструмента — артефакт, от несовместимого изменения сборка краснеет ещё до прода.
Теперь деталь. В десятом модуле несовместимость била громко: обработчик падал, алёрт орал, все бежали чинить. У нового потребителя всё наоборот: LLM «читает» имена и описания инструментов семантически. Переименуй параметр, перепиши описание — и большинство чужих агентов… продолжат работать. Просто некоторые начнут звать инструмент чуть иначе, чуть реже или чуть не с теми аргументами. Ни одного исключения, ни одного упавшего теста — у партнёра просто «стало хуже», и никто не свяжет это с нашим релизом. Деградация стала тихой. И потому контракт здесь не менее, а более важен: он — единственное, что вообще можно зафиксировать.
Отсюда практика: изменения описаний инструментов проходят тот же ритуал, что изменения схем, — реестр, ревью, канарейка; а рядом живёт мониторинг использования: как часто зовут каждый инструмент, с какими ошибками. Сдвиг паттерна после релиза — сигнал тихой поломки.
И последний слой — безопасность, потому что на том конце . Аутентификация: кто ты (токены, партнёрские учётки). Авторизация: что тебе можно (чтение — всем, заказы — по договору). Лимиты: сколько можно (запросов в минуту, заказов в сутки, сумм в рублях). Журнал: что ты делал (каждый вызов — в аудит). Валидация параметров — параноидальная: чужая модель может прислать что угодно, включая очень странные строки. Почему «странные строки» — это отдельная большая тема, узнаешь в следующем модуле.