Работа с 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;
• канонический интерфейс вызова, если пользователь имеет право.

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

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

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

Поиск

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

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

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

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

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

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

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

Используйте только URL из этой формы, без подмены агента, версии или внутренней службы через заголовок, параметр или тело. Вызов проходит через Platform Agent Gateway, который повторно проверяет токен и право на вызов агента agent#invoke, затем заменяет исходный пользовательский токен на короткоживущее удостоверение, связанное с конкретным агентом. Известный URL без права не позволяет обойти шлюз.

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

В каталоге вы увидите только записи в состоянии 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-код и идентификатор агента.

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