Перейти к содержанию
Публикация AiManual

Кастомные метаданные в AWS Agent Registry: схема, валидация и автоодобрение MCP-серверов

Разбираем кастомные схемы метаданных в AWS Agent Registry: типы полей Text, Enum, URL и Boolean, статус NON_COMPLIANT, ошибку ValidationException, обогащение да

Коротко

Что будет в материале

  1. 01

    Зачем парку агентов и MCP-серверов единая схема метаданных

  2. 02

    Как устроена валидация: NON_COMPLIANT и ValidationException

  3. 03

    Сквозной сценарий: от схемы до автоматического одобрения MCP-сервера

  4. 04

    Поиск и фильтрация записей по метаданным

Зачем парку агентов и 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. Схему определяет администратор реестра, а реестр проверяет по ней каждую запись при создании и обновлении.

ПолеТипДопустимые значения (пример)ОбязательностьПрименимость
environmentEnumdev, staging, prodОбязательноеВсе типы записей
businessUnitEnumfinance, retail, platform, researchОбязательноеВсе типы записей
securityScanStatusEnumpassed, failed, pendingОбязательноеВсе типы записей
ownerTeamTextсвободный текстНеобязательноеВсе типы записей
docsUrlURLссылка на runbook командыНеобязательноеВсе типы записей
networkEgressEnumnone, 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. Она связывает их данные с каталогом и делает пригодными для фильтров и автоматики. Сами данные по-прежнему живут в системах-источниках.

Порядок действий перед включением:

  1. Определите обязательные поля и не добавляйте больше пяти на первом этапе.
  2. Согласуйте значения перечислений с командами, которые будут их заполнять, а не только с платформой.
  3. Продумайте маппинг значений из сканера безопасности и CMDB, проверьте его на реальных выгрузках.
  4. Настройте обогащение и протестируйте на записи вне продакшена: так видны ValidationException до того, как они остановят публикацию.
  5. Настройте правила автоодобрения в Lambda, оставив ручное ревью для чувствительных случаев.
  6. Только после этого переводите новые поля в обязательные и предупредите владельцев существующих записей о статусе NON_COMPLIANT.

Такой порядок даёт реестру то, ради чего он нужен: предсказуемый каталог, в котором и человек, и агент находят нужный MCP-сервер по одинаково понятным признакам.

Подписаться на канал