Вызов и ответ

Подключение

Параметр	Значение
Протокол	`streamable-http`
Формат вызова	`jsonrpc-2.0`
Авторизация	`Bearer`, токен выдаётся при подключении сервера к платформе

Если схема аргументов, которую сервер объявил в tools/list, запрещает дополнительные поля, платформа перед вызовом убирает аргументы, которых в ней нет. Поэтому новые необязательные аргументы контракта не ломают сервер со строгой схемой. При открытой схеме ничего не убирается.

Принципал

Кто вызывает инструмент, сервер узнаёт из принципала — подписанного платформой токена в отдельном заголовке.

Параметр	Значение
Заголовок	`X-Norm-Principal`
Алгоритм подписи	`ES256`
Ключи для проверки	`/.well-known/norm-jwks.json` по адресу из утверждения `iss`
Наибольший срок жизни	300 с

Утверждения принципала. Кто пользователь, из какого тенанта, с какими правами, каким способом вошёл и каким токеном провайдера это можно подтвердить.

Поле	Обязательно	Тип
`aud`	да	string
`auth_method`	да	string
`correlation_id`	да	string
`delegation_id`	да	string
`exp`	да	integer
`iat`	да	integer
`iss`	да	string
`jti`	да	string
`role`	да	string
`scopes`	да	список string
`sub`	да	string
`tenant`	да	string
`provider_token`	нет	string

Сервер проверяет принципал в два шага. Первый обязателен: подпись по ключам платформы, совпадение aud со своим подключением и срок действия. Второй — по выбору бизнеса: подтвердить у провайдера по auth_method и provider_token, что пользователь ещё действующий. Токен провайдера разрешён только для этой проверки, не для доступа к данным провайдера от имени пользователя; в журналах и отчётах он маскируется.

Ответ инструмента

Успешный ответ любого инструмента каталога — это structuredContent из двух частей: обязательного конверта и данных инструмента в поле data. Поля data описаны у каждого инструмента в разделе «Каталог инструментов».

Конверт ответа. Обязательная часть успешного ответа любого инструмента каталога: откуда данные, насколько свежи, есть ли продолжение. Дополнительные поля разрешены: ответ сервера может быть шире контракта.

Поле	Обязательно	Тип	Что это
`freshness`	да	`Freshness`	Свежесть
`source_refs`	да	список `SourceRef`
`page`	нет	`Page`	Страница

SourceRef

Ссылка на источник. Система-источник, ключ записи в ней и человекочитаемая подпись.

Поле	Обязательно	Тип
`ref`	да	string
`source`	да	string
`label`	нет	string

Freshness

Свежесть. Момент данных, срок годности в секундах и признак устаревания.

Поле	Обязательно	Тип
`as_of`	да	string (date-time)
`stale`	да	boolean
`ttl_sec`	да	integer

Page

Страница. Есть ли ещё данные и непрозрачный курсор для следующей страницы.

Поле	Обязательно	Тип
`has_more`	да	boolean
`next_cursor`	нет	string

Постраничная выдача

Инструмент с пометкой «списковый» отдаёт данные страницами. Он обязан принимать аргументы limit и cursor и возвращать в конверте page. Курсор непрозрачен: клиент передаёт page.next_cursor как есть, не разбирая его.

ListInput

Вход спискового инструмента. Размер страницы и непрозрачный курсор. Обязателен у инструмента, помеченного list: true.

Поле	Обязательно	Тип
`cursor`	нет	string
`limit`	нет	integer

Пределы

Предел	Значение	Что ограничивает
`max_result_chars`	32000	символов в сериализованном `structuredContent` ответа
`max_page_size`	200	элементов на странице спискового инструмента
`principal_max_ttl_sec`	300	секунд жизни подписанного принципала
`transcript_default_chars`	12000	символов в окне расшифровки по умолчанию
`transcript_max_chars`	24000	символов в окне расшифровки наибольшее