Wszystkie metody są wywoływane przez POST pod adresem https://www.magisterium.com/api/v1/a2a z użyciem JSON-RPC 2.0. Każde żądanie musi zawierać Authorization: Bearer $MAGISTERIUM_TOKEN (token użytkownika wydany przez OAuth — zobacz Uwierzytelnianie) oraz Content-Type: application/json.

Metody

message/send

Wyślij wiadomość do umiejętności i otrzymaj ukończone zadanie. Wszystkie umiejętności Magisterium są synchroniczne — odpowiedź zawiera terminalny stan zadania (completed lub failed), nigdy pośredni status working.

Parametry:

Pole	Typ	Wymagane	Opis
message	Message	Tak	Wiadomość użytkownika z częściami i opcjonalnymi metadanymi.
message.role	string	Tak	Musi być "user".
message.messageId	string	Tak	Unikalne ID dla tej wiadomości.
message.kind	string	Tak	Musi być "message".
message.parts	Part[]	Tak	Co najmniej jedna część (text lub data).
message.metadata.skillId	string	Nie	Umiejętność do wywołania. Domyślnie catholic_qa.
message.contextId	string	Nie	Opcjonalne ID kontekstu do grupowania powiązanych zadań. Jeśli pominięte, serwer je wygeneruje.
configuration	object	Nie	Zarezerwowane do przyszłego użytku.

Zwraca: Obiekt Task z kind: "task".

tasks/get

Pobierz wcześniej utworzone zadanie po jego ID.

Parametry:

Pole	Typ	Wymagane	Opis
id	string	Tak	ID zadania zwrócone z message/send.

Zwraca: Obiekt Task lub błąd TASK_NOT_FOUND, jeśli zadanie wygasło lub nie istnieje. Zadania są przechowywane przez 24 godziny.

tasks/cancel

Anuluj zadanie, jeśli znajduje się w stanie umożliwiającym anulowanie. Ponieważ wszystkie umiejętności są realizowane synchronicznie, większość zadań jest już w stanie terminalnym (completed / failed) w chwili zwrócenia odpowiedzi — próba anulowania zadania terminalnego zwraca INVALID_PARAMS z komunikatem Invalid state transition.

Parametry:

Pole	Typ	Wymagane	Opis
id	string	Tak	ID zadania do anulowania.

Zwraca: Zaktualizowany obiekt Task ze status.state: "canceled".

Cykl życia zadania

Umiejętności Magisterium działają synchronicznie, więc zadanie jest zapisywane w pamięci dopiero po zakończeniu umiejętności — zawsze w stanie terminalnym. Stany submitted i working są częścią szerszej specyfikacji A2A, ale implementacja Magisterium nigdy ich nie produkuje; zawsze zaobserwujesz tylko jeden z trzech stanów terminalnych poniżej.

Stan	Znaczenie
completed	Terminalny — wyniki są w artifacts. Zwracany przez message/send, gdy umiejętność zakończy się pomyślnie.
failed	Terminalny — status.message zawiera przyczynę niepowodzenia. Zwracany przez message/send, gdy umiejętność rzuci wyjątek.
canceled	Terminalny — osiągalny tylko przez wywołanie tasks/cancel na nieterminalnym zadaniu. Ponieważ zadania są już w stanie terminalnym, gdy message/send zwraca odpowiedź, w praktyce anulowanie jest odrzucane z INVALID_PARAMS dla każdego zadania, do którego masz odniesienie.

Każde zadanie zawiera też:

• contextId — identyfikator grupujący, który możesz ponownie wykorzystać w kolejnych wiadomościach, aby powiązać pokrewne zadania.
• history — uporządkowaną listę wiadomości użytkownika i agenta, które wytworzyły artefakty zadania.

Kody błędów

Kod	Nazwa	Opis
-32700	Parse error	Nieprawidłowe ciało JSON.
-32600	Invalid request	Brak pól jsonrpc, method lub id.
-32601	Method not found	Nieznana metoda JSON-RPC.
-32602	Invalid params	Brakujące lub nieprawidłowe parametry (również zwracane dla nieprawidłowych przejść stanu tasks/cancel).
-32603	Internal error	Nieoczekiwany błąd po stronie serwera.
-32001	Task not found	ID zadania nie istnieje lub wygasło.
-32002	Skill not found	Nieznane skillId w metadanych wiadomości.
-32003	Rate limit exceeded	Zbyt wiele żądań. Sprawdź retryAfter (sekundy) w data błędu.
-32004	Unauthorized	Brak lub nieprawidłowy token Bearer.
-32005	Paid plan required	A2A wymaga planu Pro, Organization lub Enterprise.

Status HTTP odzwierciedla klasę błędu: 401 dla UNAUTHORIZED, 403 dla PLAN_REQUIRED, 429 dla RATE_LIMITED oraz 200 dla wszystkich pozostałych błędów JSON-RPC (zgodnie z konwencją JSON-RPC zwracającą 200 z ciałem error).

Limity żądań

A2A dzieli ten sam pool limitów żądań co MCP — zobacz Cennik MCP dla limitów żądań na plan.

Wymuszane są dwa warianty:

• Default — dotyczy document_search, document_fetch, liturgical_readings i saints_of_the_day.
• Expensive — dotyczy wyłącznie catholic_qa, ponieważ uruchamia pipeline odpowiedzi oparty na LLM. Ten wariant używa bardziej restrykcyjnego, niższego limitu.

Po osiągnięciu limitu obiekt data błędu zawiera retryAfter w sekundach. Wywołujący powinni odczekać ten interwał przed ponowieniem.

CORS

Endpoint odpowiada na żądania preflight OPTIONS i zwraca permisywne nagłówki CORS (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), dzięki czemu A2A może być wywoływany z orkiestratorów przeglądarkowych bez proxy.