Minden metódus POST kéréssel hívható a https://www.magisterium.com/api/v1/a2a címen JSON-RPC 2.0 használatával. Minden kérésnek tartalmaznia kell az Authorization: Bearer $MAGISTERIUM_TOKEN (OAuth által kibocsátott felhasználói token — lásd Hitelesítés) és Content-Type: application/json fejléceket.

Metódusok

message/send

Küldjön üzenetet egy képességnek, és kapjon befejezett feladatot. Minden Magisterium képesség szinkron — a válasz a feladat terminális állapotát tartalmazza (completed vagy failed), soha nem a közbenső working állapotot.

Paraméterek:

Mező	Típus	Kötelező	Leírás
message	Message	Igen	A felhasználói üzenet részekkel és opcionális metaadatokkal.
message.role	string	Igen	"user" értékűnek kell lennie.
message.messageId	string	Igen	Az üzenet egyedi azonosítója.
message.kind	string	Igen	"message" értékűnek kell lennie.
message.parts	Part[]	Igen	Legalább egy rész (text vagy data).
message.metadata.skillId	string	Nem	A meghívandó képesség. Alapértelmezett: catholic_qa.
message.contextId	string	Nem	Opcionális kontextus-azonosító kapcsolódó feladatok csoportosításához. Ha kimarad, a szerver generál egyet.
configuration	object	Nem	Jövőbeli használatra fenntartva.

Visszaad: egy Task objektumot kind: "task" értékkel.

tasks/get

Korábban létrehozott feladat lekérése az azonosítója alapján.

Paraméterek:

Mező	Típus	Kötelező	Leírás
id	string	Igen	A message/send-ből visszakapott feladatazonosító.

Visszaad: A Task objektumot, vagy TASK_NOT_FOUND hibát, ha a feladat lejárt vagy hiányzik. A feladatokat 24 órán át tároljuk.

tasks/cancel

Szakítson meg egy feladatot, ha megszakítható állapotban van. Mivel minden képesség szinkron módon zárul, a válasz visszatérésének pillanatában a feladatok nagy része már terminális állapotban van (completed / failed) — egy terminális feladat megszakításának kísérlete INVALID_PARAMS hibát ad vissza Invalid state transition üzenettel.

Paraméterek:

Mező	Típus	Kötelező	Leírás
id	string	Igen	A megszakítandó feladat azonosítója.

Visszaad: A frissített Task objektumot status.state: "canceled" értékkel.

Feladat életciklus

A Magisterium képességei szinkron módon futnak, ezért a feladat csak a képesség befejezése után kerül a tárolóba — mindig terminális állapotban. A submitted és working állapotok a tágabb A2A specifikáció részei, de a Magisterium implementációja soha nem hozza létre őket; mindig csak az alábbi három terminális állapot egyikét fogja megfigyelni.

Állapot	Jelentés
completed	Terminális — az eredmények az artifacts mezőben vannak. A message/send adja vissza, amikor a képesség sikeresen befejeződik.
failed	Terminális — a status.message tartalmazza a hiba okát. A message/send adja vissza, amikor a képesség kivételt dob.
canceled	Terminális — csak úgy érhető el, ha a tasks/cancel-t hívja egy nem terminális feladaton. Mivel a feladatok már terminális állapotban vannak, mire a message/send visszatér, a gyakorlatban a megszakítást INVALID_PARAMS hibával utasítja vissza minden olyan feladat esetén, amelyre hivatkozása van.

Minden feladat tartalmazza továbbá:

• contextId — csoportosítási azonosító, amelyet újrahasználhat követő üzeneteiben a kapcsolódó feladatok összekapcsolására.
• history — a felhasználói és ügynöki üzenetek rendezett listája, amelyek a feladat artefaktumait eredményezték.

Hibakódok

Kód	Név	Leírás
-32700	Parse error	Érvénytelen JSON törzs.
-32600	Invalid request	Hiányzó jsonrpc, method vagy id mezők.
-32601	Method not found	Ismeretlen JSON-RPC metódus.
-32602	Invalid params	Hiányzó vagy érvénytelen paraméterek (érvénytelen tasks/cancel állapotátmeneteknél is visszaadható).
-32603	Internal error	Váratlan szerveroldali hiba.
-32001	Task not found	A feladat azonosítója nem létezik vagy lejárt.
-32002	Skill not found	Ismeretlen skillId az üzenet metaadataiban.
-32003	Rate limit exceeded	Túl sok kérés. Ellenőrizze a retryAfter (másodperc) értéket a hiba data mezőjében.
-32004	Unauthorized	Hiányzó vagy érvénytelen Bearer token.
-32005	Paid plan required	Az A2A Pro, Organization vagy Enterprise csomagot igényel.

Az HTTP státusz tükrözi a hibaosztályt: 401 UNAUTHORIZED esetén, 403 PLAN_REQUIRED esetén, 429 RATE_LIMITED esetén, és 200 minden más JSON-RPC hiba esetén (a JSON-RPC konvenció szerint, amely 200-at ad vissza error törzzsel).

Kérési korlátok

Az A2A ugyanazt a kéréskorlát-készletet használja, mint az MCP — lásd az MCP Árazás oldalt a csomagonkénti kéréskorlátokért.

Két változat van érvényben:

• Default — a document_search, document_fetch, liturgical_readings és saints_of_the_day képességekre vonatkozik.
• Expensive — kizárólag a catholic_qa-ra vonatkozik, mivel az LLM-alapú válasz-pipelinet futtat. Ez a változat szigorúbb, alacsonyabb plafont használ.

Ha eléri a korlátot, a hiba data objektuma retryAfter értéket tartalmaz másodpercben. A hívóknak ennek az intervallumnak megfelelően vissza kell vonulniuk az újrapróbálkozás előtt.

CORS

A végpont válaszol az OPTIONS preflight kérésekre és megengedő CORS fejléceket ad vissza (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), így az A2A meghívható böngészőalapú orkesztrátorokból proxy nélkül.