AI Platform Docs

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

Атрибут	Значение
Базовый путь	`/api/v1`
OpenAPI	`3.1.2`
JSON Schema	`2020-12`
Версия контракта	`0.1-draft`
Состояние	`proposed`
Удостоверение	OIDC/JWT для защищенных операций
Авторизация	Актуальная проверка конкретного ресурса в SpiceDB
Связь запросов	W3C Trace Context и `traceId` в ответе

Скачать OpenAPI JSON

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

Операции

Метод и путь	Назначение	Право
`GET /api/v1/agents`	Страница разрешенных агентских записей	`view` для каждой возвращаемой записи
`GET /api/v1/agents/{agentId}`	Одна разрешенная запись	`view`; интерфейс вызова требует также `invoke`
`POST /api/v1/agents/search`	Гибридный поиск разрешенных кандидатов	`invoke` для каждого результата
`GET /health/live`	Работоспособность процесса	Определяется политикой границы среды
`GET /health/ready`	Готовность обслуживать запросы	Определяется политикой границы среды

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

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

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

Курсор:

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

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

Пример:

GET /api/v1/agents?workspaceId=workspace-1&protocol=a2a&implementationType=low-code&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