AI Platform Docs

Состояние контракта

Атрибут	Значение
Базовый путь	`/api/v2`
OpenAPI	`3.1.2`
JSON Schema	`2020-12`
Версия контракта	`2.0-r2`
Состояние	`accepted-by-ADR-0002-and-ADR-0003`
Удостоверение	OIDC/JWT (Bearer) для защищённых операций
Авторизация	Прямая проверка разрешения в Platform AuthZ (SpiceDB)
Связь запросов	W3C Trace Context и `traceId` в ответе

Скачать OpenAPI JSON

SHA-256 и путь нормативного источника опубликованы в манифесте артефактов.

Операции

Метод и путь	Назначение	Право
`GET /api/v2/agents`	Страница активных агентов, видимых через `agent#view`	`agent#view` для каждой возвращаемой записи
`GET /api/v2/agents/{agentId}`	Одна активная запись по UUIDv7	`agent#view`
`POST /api/v2/agents/search`	Гибридный поиск активных агентов, каждый кандидат фильтруется через `agent#view`	`agent#view`
`GET /api/v2/drift`	Текущий дрейф платформы по allowlist наблюдений	`platform#view_drift` на ресурсе `platform:agent-platform`
`GET /health/live`	Работоспособность процесса	Определяется политикой границы среды
`GET /health/ready`	Готовность обслуживать запросы	Определяется политикой границы среды

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

Возвращает только активные (lifecycleStatus = active) записи, видимые через agent#view. Поддерживаются фильтры протокола, типа реализации выбранной версии и прямого владельца. Ограничение размера страницы является ограниченным сервером числом.

Доступные параметры:

Параметр	Значение
`protocol`	Массив: `a2a`, `mcp`
`implementationType`	Массив: `sdk`, `low-code`. SDK наблюдается при включённом профиле `sdk-helm/v1`; low-code публикуется через R2-адаптер CP
`ownerType`	`principal` или `service`; должен передаваться вместе с `ownerIssuer` и `ownerSubject`
`ownerIssuer`	URI издателя неизменяемой идентичности; вместе с `ownerType` и `ownerSubject`
`ownerSubject`	Неизменяемый subject у издателя; вместе с `ownerType` и `ownerIssuer`
`cursor`	Оpaque-курсор для постраничной навигации
`limit`	1–100, по умолчанию 20

Курсор:

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

Тип реализации sdk|low-code и протокол a2a|mcp применяются независимо и совместно. Значение mcp не является типом реализации.

Пример:

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>

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

Получение одной записи

agentId — непрозрачный UUID. Скрытая и отсутствующая запись возвращают одинаковый 404.

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

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

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

Интерфейс вызова

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

Поле	Значение
`url`	Канонический HTTPS-адрес Platform Agent Gateway для конкретных Agent и AgentVersion
`protocolBinding`	Принятая привязка A2A HTTP+JSON или MCP Streamable HTTP
`exposure`	`public_gateway`
`authorization`	`platform_oidc_spicedb`

Клиент не подменяет агента, версию и внутреннюю службу через заголовок, параметр или тело. Известный URL без права не позволяет обойти Platform Agent Gateway.

Поиск

Запрос содержит текст, рабочую область, необязательный профиль, протоколы, типы реализации, topK и необязательный более строгий minScore. Поля userId, роли и решение о доступе запрещены.

Ответ содержит только разрешенные совпадения выше порога. Смысловая и лексическая оценки не обходят проверку SpiceDB. Если подходящих результатов нет, возвращается 200 и matches: [].

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

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

Текст запроса не должен сохраняться в PostgreSQL, OpenSearch, Redpanda, журнале аудита и телеметрии.

Ошибки

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

HTTP	Класс ошибки
400 или 422	Неверная форма, фильтр, курсор или детерминированная проверка
401	Отсутствует, недействительно или просрочено удостоверение
403	Подтвержденному субъекту запрещена команда или диагностика
404	Объект отсутствует либо намеренно скрыт
409	Конфликт неизменяемой идентичности или жизненного цикла
429	Превышено принятое ограничение частоты или параллельности
503	Недоступна авторизация, векторизация или поиск
504	Внешняя зависимость не ответила за установленное время
500	Непредвиденная ошибка с очищенным сообщением

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

Совместимость

Потребитель фиксирует SHA-256 OpenAPI и проверяет различия перед обновлением. Несовместимое изменение поля, пути или права требует новой версии API либо принятого периода перехода, проверок поставщика и потребителя и условия удаления прежней формы.

API Agent Registry