Všechny metody se volají přes POST na https://www.magisterium.com/api/v1/a2a pomocí JSON-RPC 2.0. Každý požadavek musí obsahovat Authorization: Bearer $MAGISTERIUM_TOKEN (uživatelský token vydaný přes OAuth — viz Autentizace) a Content-Type: application/json.

Metody

message/send

Odeslat zprávu dovednosti a obdržet dokončenou úlohu. Všechny dovednosti Magisterium jsou synchronní — odpověď obsahuje terminální stav úlohy (completed nebo failed), nikdy ne mezistav working.

Parametry:

Pole	Typ	Povinné	Popis
message	Message	Ano	Zpráva uživatele s částmi a volitelnými metadaty.
message.role	string	Ano	Musí být "user".
message.messageId	string	Ano	Unikátní ID pro tuto zprávu.
message.kind	string	Ano	Musí být "message".
message.parts	Part[]	Ano	Minimálně jedna část (text nebo data).
message.metadata.skillId	string	Ne	Dovednost pro vyvolání. Výchozí hodnota je catholic_qa.
message.contextId	string	Ne	Volitelné ID kontextu pro seskupování souvisejících úloh. Pokud chybí, server jej vygeneruje.
configuration	object	Ne	Rezervováno pro budoucí použití.

Vrací: Objekt Task s kind: "task".

tasks/get

Načíst dříve vytvořenou úlohu podle jejího ID.

Parametry:

Pole	Typ	Povinné	Popis
id	string	Ano	ID úlohy vrácené z message/send.

Vrací: Objekt Task nebo chybu TASK_NOT_FOUND, pokud vypršel nebo chybí. Úlohy jsou ukládány po dobu 24 hodin.

tasks/cancel

Zrušit úlohu, pokud je ve zrušitelném stavu. Protože všechny dovednosti se vykonávají synchronně, většina úloh je v době vrácení odpovědi již v terminálním stavu (completed / failed) — pokus o zrušení terminální úlohy vrátí INVALID_PARAMS se zprávou Invalid state transition.

Parametry:

Pole	Typ	Povinné	Popis
id	string	Ano	ID úlohy ke zrušení.

Vrací: Aktualizovaný objekt Task se status.state: "canceled".

Životní cyklus úlohy

Dovednosti Magisteria běží synchronně, takže úloha je do úložiště uložena teprve poté, co dovednost skončí — vždy v terminálním stavu. Stavy submitted a working jsou součástí širší specifikace A2A, ale implementace Magisteria je nikdy neprodukuje; vždy uvidíte pouze jeden ze tří níže uvedených terminálních stavů.

Stav	Význam
completed	Terminální — výsledky jsou v artifacts. Vráceno message/send, když dovednost úspěšně dokončí.
failed	Terminální — status.message obsahuje důvod selhání. Vráceno message/send, když dovednost vyhodí výjimku.
canceled	Terminální — dosažitelné pouze voláním tasks/cancel na neterminální úloze. Protože jsou úlohy v okamžiku, kdy se message/send vrací, již v terminálním stavu, je v praxi zrušení odmítnuto s INVALID_PARAMS pro jakoukoliv úlohu, na kterou máte odkaz.

Každá úloha navíc obsahuje:

• contextId — seskupovací identifikátor, který můžete znovu použít napříč navazujícími zprávami k propojení souvisejících úloh.
• history — uspořádaný seznam zpráv uživatele a agenta, které vytvořily artefakty úlohy.

Chybové kódy

Kód	Název	Popis
-32700	Parse error	Neplatné tělo JSON.
-32600	Invalid request	Chybí pole jsonrpc, method nebo id.
-32601	Method not found	Neznámá JSON-RPC metoda.
-32602	Invalid params	Chybějící nebo neplatné parametry (také vraceno pro neplatné přechody stavu tasks/cancel).
-32603	Internal error	Neočekávané selhání na straně serveru.
-32001	Task not found	ID úlohy neexistuje nebo vypršelo.
-32002	Skill not found	Neznámé skillId v metadatech zprávy.
-32003	Rate limit exceeded	Příliš mnoho požadavků. Zkontrolujte retryAfter (sekundy) v data chyby.
-32004	Unauthorized	Chybějící nebo neplatný Bearer token.
-32005	Paid plan required	A2A vyžaduje plán Pro, Organization nebo Enterprise.

HTTP status odráží třídu chyby: 401 pro UNAUTHORIZED, 403 pro PLAN_REQUIRED, 429 pro RATE_LIMITED a 200 pro všechny ostatní chyby JSON-RPC (podle konvence JSON-RPC vracet 200 s tělem error).

Limity požadavků

A2A sdílí stejný pool limitů požadavků jako MCP — viz Ceník MCP pro limity požadavků podle jednotlivých plánů.

Jsou vynucovány dvě varianty:

• Default — platí pro document_search, document_fetch, liturgical_readings a saints_of_the_day.
• Expensive — platí pouze pro catholic_qa, protože spouští pipeline odpovědí poháněnou LLM. Tato varianta používá přísnější, nižší limit.

Když dosáhnete limitu, objekt data chyby obsahuje retryAfter v sekundách. Volající by měli před opakováním tento interval vyčkat.

CORS

Endpoint odpovídá na preflight požadavky OPTIONS a vrací permisivní CORS hlavičky (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), takže A2A lze volat z orchestrátorů v prohlížeči bez proxy.