Все методы вызываются через POST по адресу https://www.magisterium.com/api/v1/a2a с использованием JSON-RPC 2.0. Каждый запрос должен включать Authorization: Bearer $MAGISTERIUM_TOKEN (пользовательский токен, выданный через OAuth — см. Аутентификацию) и Content-Type: application/json.

Методы

message/send

Отправить сообщение навыку и получить завершённую задачу. Все навыки Magisterium синхронны — ответ содержит терминальное состояние задачи (completed или failed), но никогда промежуточный статус working.

Параметры:

Поле	Тип	Обязательное	Описание
message	Message	Да	Сообщение пользователя с частями и необязательными метаданными.
message.role	string	Да	Должно быть "user".
message.messageId	string	Да	Уникальный ID для этого сообщения.
message.kind	string	Да	Должно быть "message".
message.parts	Part[]	Да	Минимум одна часть (text или data).
message.metadata.skillId	string	Нет	Навык для вызова. По умолчанию catholic_qa.
message.contextId	string	Нет	Необязательный ID контекста для группировки связанных задач. Если опущен, сервер сгенерирует его.
configuration	object	Нет	Зарезервировано для будущего использования.

Возвращает: Объект Task с kind: "task".

tasks/get

Получить ранее созданную задачу по её ID.

Параметры:

Поле	Тип	Обязательное	Описание
id	string	Да	ID задачи, возвращённый из message/send.

Возвращает: Объект Task, либо ошибку TASK_NOT_FOUND, если задача истекла или отсутствует. Задачи хранятся 24 часа.

tasks/cancel

Отменить задачу, если она находится в отменяемом состоянии. Поскольку все навыки разрешаются синхронно, большинство задач уже находятся в терминальном состоянии (completed / failed) к моменту возврата ответа — попытка отменить терминальную задачу возвращает INVALID_PARAMS с сообщением Invalid state transition.

Параметры:

Поле	Тип	Обязательное	Описание
id	string	Да	ID задачи для отмены.

Возвращает: Обновлённый объект Task с status.state: "canceled".

Жизненный цикл задачи

Навыки Magisterium выполняются синхронно, поэтому задача сохраняется в хранилище только после завершения навыка — всегда в терминальном состоянии. Состояния submitted и working являются частью более широкой спецификации A2A, но никогда не создаются реализацией Magisterium; вы всегда будете наблюдать только одно из трёх терминальных состояний ниже.

Состояние	Значение
completed	Терминальное — результаты находятся в artifacts. Возвращается message/send, когда навык успешно завершается.
failed	Терминальное — status.message содержит причину сбоя. Возвращается message/send, когда навык выбрасывает исключение.
canceled	Терминальное — достижимо только при вызове tasks/cancel для нетерминальной задачи. Поскольку к моменту возврата message/send задачи уже находятся в терминальном состоянии, на практике отмена отклоняется с INVALID_PARAMS для любой задачи, к которой у вас есть доступ.

Каждая задача также содержит:

• contextId — групповой идентификатор, который можно повторно использовать для последующих сообщений, чтобы связывать связанные задачи.
• history — упорядоченный список сообщений пользователя и агента, которые привели к артефактам задачи.

Коды ошибок

Код	Имя	Описание
-32700	Parse error	Некорректное тело JSON.
-32600	Invalid request	Отсутствуют поля jsonrpc, method или id.
-32601	Method not found	Неизвестный метод JSON-RPC.
-32602	Invalid params	Отсутствуют или некорректны параметры (также возвращается при недопустимых переходах состояний tasks/cancel).
-32603	Internal error	Непредвиденный сбой на стороне сервера.
-32001	Task not found	ID задачи не существует или истёк.
-32002	Skill not found	Неизвестный skillId в метаданных сообщения.
-32003	Rate limit exceeded	Слишком много запросов. Проверьте retryAfter (в секундах) в data ошибки.
-32004	Unauthorized	Отсутствует или недействителен Bearer-токен.
-32005	Paid plan required	A2A требует план Pro, Organization или Enterprise.

HTTP-статус отражает класс ошибки: 401 для UNAUTHORIZED, 403 для PLAN_REQUIRED, 429 для RATE_LIMITED и 200 для всех остальных ошибок JSON-RPC (согласно конвенции JSON-RPC возвращать 200 с телом error).

Лимиты запросов

A2A использует тот же пул лимитов запросов, что и MCP — см. Цены MCP для пределов запросов по каждому плану.

Применяются два варианта:

• Default — применяется к document_search, document_fetch, liturgical_readings и saints_of_the_day.
• Expensive — применяется только к catholic_qa, так как он запускает LLM-конвейер формирования ответа. Этот вариант использует более строгий, сниженный лимит.

При достижении лимита объект data ошибки содержит retryAfter в секундах. Вызывающие стороны должны выдержать этот интервал перед повторной попыткой.

CORS

Эндпоинт отвечает на предварительные запросы OPTIONS и возвращает разрешительные заголовки CORS (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), поэтому A2A может вызываться из браузерных оркестраторов без прокси.