Работа с Agent Registry

Назначение каталога

Agent Registry отображает список агентов, автоматически обнаруженных в Kubernetes.

Каталог возвращает только активные записи. Пользователь видит те из них, для которых авторизационное ядро подтвердило право просмотра agent#view.

Создать, изменить, удалить, развернуть или вызвать агента через API каталога нельзя: состояние формируется из наблюдения, а вызов выполняется через Platform Agent Gateway.

Вход

Для входа откройте в браузере URL Swagger UI, нажмите Authorize и выберите oauth2Password и введите логин и пароль вашей учетной записи.

Базовый путь интерфейса — /api/v2. Для защищенных операций требуется удостоверение OIDC/JWT (Bearer); каждый ответ содержит traceId для диагностики.

Просмотр списка

Выполните GET /api/v2/agents?limit=20. Ответ содержит только активные записи (lifecycleStatus = active), видимые через agent#view. Каждая запись содержит безопасные сведения об агенте, выбранной версии, протоколе, состоянии и владельце.

Доступные фильтры:

Протокол и тип реализации применяются независимо и совместно. Например, служба MCP может иметь тип low-code, а агент A2A — тип sdk. Значение mcp — это протокол, а не тип реализации.

Курсор:

• зашифрован и защищен от изменения;
• связан с вашим удостоверением и полным набором фильтров;
• не содержит количество скрытых объектов;
• становится недействительным после ротации ключа;
• при ошибке возвращает cursor_invalid и не открывает страницу без фильтров.

Не переносите курсор в запрос другого пользователя и не изменяйте фильтры между страницами. Не передавайте идентификатор пользователя и готовое решение о правах в параметрах запроса.

Пример:

GET /api/v2/agents?protocol=a2a&implementationType=low-code&ownerType=principal&ownerIssuer=https%3A%2F%2Fidp.platform&ownerSubject=user-123&limit=20 Authorization: Bearer <platform-token>

Просмотр одной записи

GET /api/v2/agents/{agentId} принимает непрозрачный UUID. Запросы к отсутствующему и недоступному агенту возвращают одинаковый ответ 404. Это защищает сам факт существования агента.

Ответ может содержать:

• безопасное имя и описание;
• идентификаторы агента и выбранной версии;
• необязательного прямого владельца и состояние;
• протокол и тип реализации;
• проверенные навыки или безопасные метаданные MCP;
• канонический интерфейс активного A2A-агента при актуальной привязке маршрута.

Ответ не содержит внутренний адрес Service или Pod, адрес получения карточки, полную исходную карточку, закрытые диагностические данные и учетные данные.

Поле интерфейса вызова возвращается только когда:

1. выбранная версия агента готова;
2. отношения доступа согласованы;
3. публичный маршрут принят и связан с текущей службой Kubernetes.

Сама запись доступна только после проверки agent#view. Отдельного права на A2A-вызов для появления интерфейса не требуется.

Поиск

POST /api/v2/agents/search принимает текст запроса, необязательный профиль, фильтры протокола и типа реализации, максимальное число результатов topK и необязательный более строгий порог minScore. Рабочие области не создают область поиска или наследуемые права. Поля workspaceId, userId, роли и готовое решение о доступе не передаются — доступ к каждому кандидату проверяется платформой.

Поиск объединяет смысловое и лексическое совпадение. Смысловая и лексическая оценки не обходят проверку прав: каждый кандидат фильтруется через agent#view, а в ответ попадают только разрешенные совпадения выше порога. Если подходящих и разрешенных агентов нет, корректный ответ содержит 200 и пустой массив matches.

Краткий пример формы запроса:

{
  "query": "агент для подготовки краткого изложения",
  "protocols": ["a2a"],
  "implementationTypes": ["low-code"],
  "topK": 10
}

Текст запроса не сохраняется в журналах и телеметрии.

Переход к вызову

Если в записи есть интерфейс, его форма содержит:

Используйте URL из этой формы. Выбранная версия отдельно указана в selectedVersion; внутренний адрес службы и временный адрес проверки публикации не используются клиентом.

Platform Agent Gateway проверяет токен платформы. В профиле authenticated_all любой пользователь или сервис с принятым токеном может вызвать активного опубликованного A2A-агента. Проверки agent#invoke нет. Этот профиль не отменяет право agent#view для каталога и не предоставляет доступ к Activity.

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

Состояния агента

В каталоге вы увидите только записи в состоянии active. Полное значение всех состояний:

Информация: В процессе обнаружения агента допустима кратковременная потеря его готовности.

Ошибки

Ответ об ошибке содержит код, сообщение, traceId и детали. Коды ошибок:

Пример формы ошибки:

{
  "error": {
    "code": "authorization_unavailable",
    "message": "Authorization service is temporarily unavailable",
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "details": []
  }
}

Что делать:

• 400/422 — исправьте запрос; не повторяйте без изменения параметров;
• 401 — повторно войдите;
• 403 — обратитесь к владельцу доступа;
• 404 — проверьте UUID и доступ; система не раскрывает, отсутствует агент или скрыт;
• 429 — повторите с задержкой, соблюдая заголовок ограничения, если он возвращен;
• 503 — при отказе поиска просмотр списка может оставаться доступным. При недоступности проверки прав чтение закрыто до её восстановления; повторите запрос позже;
• 504 — повторите операцию чтения.

Ошибка не раскрывает стек, токен, внутренний URL, текст запроса или карточки и существование запрещенного кандидата.

При обращении в поддержку передавайте traceId, время, HTTP-код и идентификатор агента.

Важно: Не передавайте токен, текст закрытого запроса, внутренний адрес и полное содержимое карточки.