Усі методи викликаються через 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 можна викликати з браузерних оркестраторів без проксі.