Зачем парку агентов и MCP-серверов единая схема метаданных
AWS Agent Registry проверяет каждую запись по схеме метаданных, которую задал администратор реестра. Схема задаёт типизированные поля с фиксированными допустимыми значениями, и ей обязаны соответствовать все записи: агенты, MCP-серверы, skills и кастомные ресурсы. Запись без метаданных сохраняется со статусом NON_COMPLIANT и не может уйти на одобрение, пока обязательные поля не заполнены. Запись с неизвестным полем, пропущенным обязательным полем или недопустимым значением отклоняется с ValidationException.
Каталог нужен, чтобы парк ресурсов оставался обозримым. AWS Agent Registry собирает агентов, MCP-серверы, skills и кастомные записи в одном месте, хранит для каждой записи имя, описание, дескриптор протокола и статус одобрения. В материале AWS механизм разобран на примере условной компании AnyCompany: она публикует MCP-сервер, обогащает запись и готовит её к поиску людьми и агентами. Как устроены уровни управления и обнаружения в этом каталоге, разбирали в статье про AWS Agent Registry как корпоративный каталог агентов, MCP и skills.
Без схемы картина предсказуемая. Одна команда пишет окружение как prod, вторая как production, третья как PROD-EU. Статус сканирования безопасности лежит в отчёте сканера, бизнес-юнит в CMDB, а апрувер при рассмотрении видит только имя и описание записи. Реестр применяет схему ко всем записям, поэтому поле environment получает одинаковое имя и одинаковые допустимые значения независимо от того, какая команда опубликовала запись. Разнобой исчезает на входе, а не на этапе разбора инцидента.
Что именно фиксирует схема: общие и типозависимые поля
Схема делится на два уровня. Первый: общие атрибуты, применимые к любому типу записей. Второй: поля, которые имеют смысл только для конкретного типа, например networkEgress для MCP-серверов. Для каждого поля администратор задаёт имя, тип, список допустимых значений и признак обязательности. Типов четыре: Text, Enum, URL и Boolean. Схему определяет администратор реестра, а реестр проверяет по ней каждую запись при создании и обновлении.
| Поле | Тип | Допустимые значения (пример) | Обязательность | Применимость |
|---|---|---|---|---|
| environment | Enum | dev, staging, prod | Обязательное | Все типы записей |
| businessUnit | Enum | finance, retail, platform, research | Обязательное | Все типы записей |
| securityScanStatus | Enum | passed, failed, pending | Обязательное | Все типы записей |
| ownerTeam | Text | свободный текст | Необязательное | Все типы записей |
| docsUrl | URL | ссылка на runbook команды | Необязательное | Все типы записей |
| networkEgress | Enum | none, internal, internet | Обязательное для MCP | Только MCP-серверы |
Значения в таблице условные: конкретный набор и обязательность задаёт администратор под свою организацию. Практическое следствие из двух уровней схемы: у агента или skill поля networkEgress нет, и это не ошибка заполнения. Типозависимые поля применяются только к своему типу записей, поэтому один и тот же JSON метаданных у MCP-сервера и у skill выглядеть не должен.
Поле environment показывает выигрыш на простом примере. Пока имя и допустимые значения одинаковы у всех команд, фильтр по prod находит прод, а не три варианта написания. Как только одна команда договорилась сама с собой писать Prod-EU, фильтры и автоматика начинают врать.
Кому это выгодно: роли в реестре
Схема работает как контракт между четырьмя ролями, и у каждой своя зона ответственности.
- Администратор реестра определяет имена полей, типы, допустимые значения и обязательность, а затем применяет схему к реестру. Обычно это платформенная команда, а не автор конкретного агента.
- Публикатор создаёт или отправляет запись и передаёт значения полей применимой схемы. Отвечает за то, что значения отражают реальность, а не заполнены для галочки.
- Апрувер рассматривает запись, опираясь на провалидированные значения: окружение, бизнес-юнит, статус сканирования видны сразу и в одинаковом формате.
- Потребители и агенты используют те же значения для поиска и фильтрации: и человек в каталоге, и агент, выбирающий инструмент, работают с одним словарём.
Жизненный цикл записи от публикации до одобрения и поиска из IDE подробно разобран в обзоре возможностей каталога. Схема метаданных добавляет к этому процессу общий язык описания.
Как устроена валидация: NON_COMPLIANT и ValidationException
Проверка происходит при создании или обновлении записи: реестр сверяет кастомные метаданные со схемой администратора. Исходов два, и путать их не стоит. Запись без метаданных сохраняется как NON_COMPLIANT, а невалидные метаданные отклоняются с ValidationException.
Первый исход: кастомных метаданных нет вообще. Реестр сохраняет запись и помечает её как NON_COMPLIANT. Отправить такую запись на одобрение нельзя, пока не заполнены обязательные поля и значения.
Второй исход: метаданные переданы, но не проходят проверку. Неизвестное поле, отсутствующее обязательное поле, значение вне перечисления, кривой URL приводят к ValidationException. Частично невалидный набор не сохраняется: запись не получит половину полей.
Правило диагностики простое. ValidationException означает ошибку в данных, её исправляют до сохранения. NON_COMPLIANT означает неполную запись, её дозаполняют. Первое похоже на отказ валидатора формы, второе на незакрытую задачу в трекере.
Почему запись без метаданных всё равно сохраняется
Запрет на сохранение ударил бы по нормальной работе: команда начала разбираться с новым MCP-сервером, схему ещё не согласовали, а запись уже нужна для обсуждения. Режим NON_COMPLIANT позволяет зафиксировать заготовку и не пускает её дальше в каталог.
Для апрувера статус NON_COMPLIANT служит сигналом: обязательные поля не заполнены, рассматривать нечего. Для автоматизации это тоже удобный маркер: правила автоодобрения такие записи просто не трогают.
Типичные ошибки при заполнении и как их избежать
- Опечатка в имени поля: securityScanstatus вместо securityScanStatus. Для реестра это неизвестное поле, отсюда ValidationException.
- Пропущенное обязательное поле: чаще всего businessUnit, потому что его значение ищут в CMDB и забывают.
- Значение вне перечисления: prod-eu, PROD, staging2. Схема принимает только то, что задал администратор.
- Неверный формат URL: ссылка на внутреннюю вики без схемы https или строка с пробелом внутри.
Совет по процессу: держите список полей и допустимых значений в репозитории рядом с манифестом MCP-сервера или в шаблоне, из которого команда берёт заготовку метаданных. Публикатор не должен помнить перечисления наизусть. Проверка на стороне реестра остаётся последним рубежом, а не заменой внутреннему линтеру в CI.
Сквозной сценарий: от схемы до автоматического одобрения MCP-сервера
Ниже путь записи на примере условной AnyCompany. Платформенная команда отвечает за реестр, продуктовые команды публикуют MCP-серверы. Имена событий, ARN и точные схемы payload зависят от вашей конфигурации AWS, их сверяют с документацией сервисов.
Регистрация MCP-сервера с обязательными полями
Первый шаг сделан администратором: схема с общими полями и networkEgress для MCP определена и применена к реестру. Дальше публикатор создаёт запись MCP-сервера и передаёт значения. Пример набора значений, а не реального ответа API:
{
"environment": "prod",
"businessUnit": "retail",
"securityScanStatus": "passed",
"ownerTeam": "supply-chain-mcp",
"networkEgress": "internal"
}
Реестр проверяет каждое значение по схеме и только после этого записывает метаданные. Для агента или skill поле networkEgress не применяется: у этих типов записей свой набор полей, и отсутствие networkEgress там не считается пробелом.
Обогащение данными из сканера и CMDB
securityScanStatus и businessUnit обычно уже существуют в других системах. Дублировать их вручную бессмысленно: расхождения неизбежны, а обновлять два места никто не любит. Интеграция подтягивает значение из сканера безопасности и из CMDB и передаёт его в реестр, где оно проходит ту же проверку, что и введённое руками.
Главная ловушка здесь в маппинге. Если сканер отдаёт PASSED или pass, а перечисление содержит passed, запись получит ValidationException и не сохранится. Маппинг значений между внешней системой и схемой продумывают до того, как поле станет обязательным, иначе первый же прогон интеграции упрётся в стену.
Граница ответственности тоже важна. Обогащение не отменяет участия публикатора: если интеграция не сработала, запись останется неполной и не уйдёт на одобрение. Логи ошибок обогащения стоит держать там же, где логи публикации.
Автоодобрение через EventBridge и Lambda
Событие о новой или обновлённой записи попадает в EventBridge, правило маршрутизирует его в Lambda. Функция читает уже провалидированные метаданные и применяет правила компании: например, одобряет автоматически, если securityScanStatus равен passed и businessUnit входит в список доверенных. Разбирать свободный текст не нужно, значения пришли из перечислений и уже проверены схемой.
Само правило живёт в коде Lambda и отражает политику организации. Реестр в этой схеме работы принимает решение, которое вы сформулировали, поэтому за корректность условий отвечает команда платформы. Для записей с networkEgress равным internet или для MCP-серверов с доступом к чувствительным данным разумно оставить ручное ревью апрувером: цена ошибочного автоодобрения выше экономии времени.
После одобрения запись становится доступной потребителям и агентам, а её метаданные начинают работать как поисковый индекс.
Поиск и фильтрация записей по метаданным
Провалидированные значения превращают каталог в управляемый список. Типичные фильтры: все MCP-серверы в prod с securityScanStatus равным passed; все записи конкретного businessUnit; MCP-серверы, у которых networkEgress не равен none, перед подключением агента к внешнему API.
Операция GetRegistryRecord возвращает значение кастомных метаданных записи. Это удобно, когда агенту или скрипту нужно проверить условие перед вызовом инструмента: сначала читаем метаданные, потом решаем, звать ли MCP-сервер. Синтаксис запросов и полный набор параметров API стоит смотреть в актуальной документации AWS Agent Registry, детали там меняются быстрее, чем общие принципы.
Надёжность фильтра держится на двух вещах: одинаковых именах полей и закрытом списке допустимых значений. Поиск не угадывает, как команда написала название окружения в этот раз, и не находит лишнего. Для агента это ещё и предсказуемость: правила выбора инструмента опираются на стабильные значения, а не на текст описания.
Ограничения, о которых стоит знать заранее
Механизм накладывает дисциплину, и у этой дисциплины есть цена. Три ограничения стоит учитывать до включения схемы.
Почему схему нельзя менять свободно
Изменения схемы аддитивные: добавить поле можно, переименовать или удалить нельзя. Причина в том, что схема работает контрактом. Если разрешить удалять поле, старые записи потеряют часть смысла, а фильтры и правила автоодобрения сломаются молча.
Аддитивность защищает существующие данные, но перекладывает аккуратность на администратора. Новое обязательное поле вводят осознанно: после его появления часть записей окажется без нужного значения. Существующие записи автоматически не переписываются, поэтому они могут стать NON_COMPLIANT и выпасть из процесса одобрения, пока владельцы их не дозаполнят.
Что происходит с уже одобренными записями при правке
Редактирование одобренной записи создаёт черновик, который снова проходит согласование. Изменение метаданных может поменять решение апрувера: скажем, networkEgress с internal на internet означает другой уровень риска, и применять такую правку молча никто не должен.
Практический вывод: группируйте изменения. Пять мелких правок подряд означают пять циклов ревью, и через неделю апрувер начнёт одобрять не глядя, что убивает весь смысл контроля. Один пакет изменений с понятным описанием экономит время всем.
Стоит ли включать схему метаданных в вашем случае
Схема оправдана, когда записей много, публикуют их несколько команд, есть требования безопасности и согласования, а поиск по каталогу входит в повседневную работу. Тогда одинаковые имена полей и закрытые перечисления экономят часы на разборе: апрувер видит статус сканирования сразу, агент фильтрует инструменты по окружению без хрупких эвристик.
Для десятка записей с одним владельцем механика избыточна. Администрирование схемы, повторные согласования после каждой правки и дозаполнение записей съедят больше времени, чем сэкономят. Начните с необязательных полей, посмотрите, заполняют ли их команды добровольно, и включайте обязательность, когда схема устоялась.
Отдельно стоит помнить, что схема не заменяет сканер безопасности и CMDB. Она связывает их данные с каталогом и делает пригодными для фильтров и автоматики. Сами данные по-прежнему живут в системах-источниках.
Порядок действий перед включением:
- Определите обязательные поля и не добавляйте больше пяти на первом этапе.
- Согласуйте значения перечислений с командами, которые будут их заполнять, а не только с платформой.
- Продумайте маппинг значений из сканера безопасности и CMDB, проверьте его на реальных выгрузках.
- Настройте обогащение и протестируйте на записи вне продакшена: так видны ValidationException до того, как они остановят публикацию.
- Настройте правила автоодобрения в Lambda, оставив ручное ревью для чувствительных случаев.
- Только после этого переводите новые поля в обязательные и предупредите владельцев существующих записей о статусе NON_COMPLIANT.
Такой порядок даёт реестру то, ради чего он нужен: предсказуемый каталог, в котором и человек, и агент находят нужный MCP-сервер по одинаково понятным признакам.