AI Platform DocsРабота с Agent Registry
Просмотр каталога, фильтрация, поиск и безопасный переход к вызову агента.
Назначение каталога
Agent Registry отображает список агентов, автоматически обнаруженных в Kubernetes.
Пользователь видит только те записи, для которых авторизационное ядро подтвердило право просмотра.
Вход
Для входа откройте в браузере URL Swagger UI, нажмите Authorize и выберите
oauth2Password и введите логин и пароль вашей учетной записи.
Просмотр списка
Выполните GET /api/v1/agents?limit=20. Запись содержит безопасные
сведения об агенте, выбранной версии, протоколе, состоянии и владельце.
Доступные фильтры:
- рабочая область;
- протокол
a2aилиmcp; - тип реализации
sdkилиlow-code; - состояние жизненного цикла;
- владелец;
- ограничение размера страницы и непрозрачный курсор.
Протокол и тип реализации агента независимы. Например, служба MCP может иметь тип
low-code, а агент A2A — тип sdk.
Курсор связан с пользователем и полным набором фильтров. Не переносите его в запрос другого пользователя и не изменяйте фильтры между страницами.
Просмотр одной записи
GET /api/v1/agents/{agentId} принимает UUID.
Запросы к отсутствующему и недоступному агенту возвращают одинаковый ответ 404.
Это защищает сам факт существования агента.
Поле интерфейса вызова возвращается только когда:
- выбранная версия агента готова;
- отношения доступа согласованы;
- публичный маршрут принят и связан с текущей службой Kubernetes;
- пользователь имеет право на вызов.
Поиск
POST /api/v1/agents/search принимает текст запроса, рабочую
область, фильтры протокола и типа реализации, максимальное число результатов и
необязательный более строгий порог.
Поиск объединяет смысловое и лексическое совпадение, затем проверяет право
вызова каждого кандидата. Если подходящих и разрешенных агентов нет, корректный
ответ содержит 200 и пустой массив matches.
Переход к вызову
Если в записи есть интерфейс, используйте его URL без подмены узла, версии или
пути. Вызов проходит через Platform Agent Gateway, который проверяет
токен, связь маршрута и право на вызов агента agent#invoke.
Состояния агента
| Состояние | Значение для пользователя |
|---|---|
active | Версия прошла проверку и может быть показана при наличии прав |
degraded | Агент существует, но нет пригодного эндпоинта; вызов недоступен |
removed | Агент подтвержденно удален; запись отсутствует в обычной выдаче |
rejected | карточка или описание агента не прошли проверку; запись не активируется |
Информация: В процессе обнаружения агента допустима кратковременная потеря его готовности.
Ошибки
| HTTP | Значение | Действие |
|---|---|---|
| 400 или 422 | Неверная форма запроса, фильтр или курсор | Исправить запрос; не повторять без изменения |
| 401 | Нет действительного токена | Повторно войти |
| 403 | Подтвержденный пользователь не имеет права на команду | Обратиться к владельцу доступа |
| 404 | Агент отсутствует либо недоступен | Проверить UUID и рабочую область; |
| 429 | Превышено ограничение частоты или параллельности | Повторить с задержкой, соблюдая заголовок ограничения, если он возвращен |
| 503 | Недоступна авторизация или поисковая служба | Повторить после восстановления; |
| 504 | Зависимая служба не ответила за установленное время | Повторить операцию чтения |
При обращении в поддержку передавайте traceId, время, HTTP-код и идентификатор агента.
Важно: Не передавайте токен, текст закрытого запроса, внутренний адрес и полное содержимое карточки.