Vse metode se kličejo preko POST na https://www.magisterium.com/api/v1/a2a z uporabo JSON-RPC 2.0. Vsaka zahteva mora vsebovati Authorization: Bearer $MAGISTERIUM_TOKEN (uporabniški žeton, izdan prek OAuth — glejte Avtentifikacijo) in Content-Type: application/json.

Metode

message/send

Pošljite sporočilo veščini in prejmite dokončano nalogo. Vse veščine Magisterium so sinhrone — odziv vsebuje terminalno stanje naloge (completed ali failed), nikoli vmesni status working.

Parametri:

Polje	Tip	Obvezno	Opis
message	Message	Da	Sporočilo uporabnika z deli in neobveznimi metapodatki.
message.role	string	Da	Mora biti "user".
message.messageId	string	Da	Edinstven ID za to sporočilo.
message.kind	string	Da	Mora biti "message".
message.parts	Part[]	Da	Najmanj en del (text ali data).
message.metadata.skillId	string	Ne	Veščina za priklic. Privzeto catholic_qa.
message.contextId	string	Ne	Neobvezen ID konteksta za združevanje povezanih nalog. Če je izpuščen, ga strežnik ustvari.
configuration	object	Ne	Rezervirano za prihodnjo uporabo.

Vrne: Objekt Task z kind: "task".

tasks/get

Pridobite predhodno ustvarjeno nalogo po njenem ID.

Parametri:

Polje	Tip	Obvezno	Opis
id	string	Da	ID naloge, vrnjen iz message/send.

Vrne: Objekt Task ali napako TASK_NOT_FOUND, če je naloga potekla ali manjka. Naloge so shranjene 24 ur.

tasks/cancel

Preklic naloge, če je v stanju, ki omogoča preklic. Ker se vse veščine razrešijo sinhrono, je večina nalog v času vrnitve odziva že v terminalnem stanju (completed / failed) — poskus preklica terminalne naloge vrne INVALID_PARAMS s sporočilom Invalid state transition.

Parametri:

Polje	Tip	Obvezno	Opis
id	string	Da	ID naloge za preklic.

Vrne: Posodobljen objekt Task s status.state: "canceled".

Življenjski cikel naloge

Veščine Magisteriuma tečejo sinhrono, zato je naloga shranjena v hrambo šele po tem, ko se veščina zaključi — vedno v terminalnem stanju. Stanji submitted in working sta del širše specifikacije A2A, vendar ju implementacija Magisteriuma nikoli ne ustvari; vedno boste opazili le eno od treh terminalnih stanj spodaj.

Stanje	Pomen
completed	Terminalno — rezultati so v artifacts. Vrne message/send, ko se veščina uspešno zaključi.
failed	Terminalno — status.message vsebuje razlog neuspeha. Vrne message/send, ko veščina vrže izjemo.
canceled	Terminalno — dosegljivo le s klicem tasks/cancel na neterminalni nalogi. Ker so naloge ob vrnitvi message/send že v terminalnem stanju, je v praksi preklic zavrnjen z INVALID_PARAMS za vsako nalogo, do katere imate dostop.

Vsaka naloga vsebuje tudi:

• contextId — identifikator združevanja, ki ga lahko ponovno uporabite v nadaljnjih sporočilih za povezovanje sorodnih nalog.
• history — urejen seznam sporočil uporabnika in agenta, ki so ustvarili artefakte naloge.

Kode napak

Koda	Ime	Opis
-32700	Parse error	Neveljavno telo JSON.
-32600	Invalid request	Manjkajo polja jsonrpc, method ali id.
-32601	Method not found	Neznana metoda JSON-RPC.
-32602	Invalid params	Manjkajoči ali neveljavni parametri (vrnjeno tudi za neveljavne prehode stanj tasks/cancel).
-32603	Internal error	Nepričakovana napaka na strani strežnika.
-32001	Task not found	ID naloge ne obstaja ali je potekel.
-32002	Skill not found	Neznan skillId v metapodatkih sporočila.
-32003	Rate limit exceeded	Preveč zahtev. Preverite retryAfter (sekunde) v data napake.
-32004	Unauthorized	Manjka ali neveljaven Bearer žeton.
-32005	Paid plan required	A2A zahteva načrt Pro, Organization ali Enterprise.

HTTP status odraža razred napake: 401 za UNAUTHORIZED, 403 za PLAN_REQUIRED, 429 za RATE_LIMITED in 200 za vse druge napake JSON-RPC (po konvenciji JSON-RPC vračati 200 s telom error).

Omejitve zahtev

A2A uporablja isti bazen omejitev zahtev kot MCP — oglejte si MCP Cenik za zgornje meje zahtev na načrt.

Uveljavljeni sta dve različici:

• Default — velja za document_search, document_fetch, liturgical_readings in saints_of_the_day.
• Expensive — velja le za catholic_qa, ker poganja LLM-podprt cevovod odgovorov. Ta različica uporablja strožjo, nižjo zgornjo mejo.

Ko dosežete omejitev, objekt data napake vsebuje retryAfter v sekundah. Klicatelji se morajo pred ponovnim poskusom umakniti za ta interval.

CORS

Končna točka se odziva na preflight zahteve OPTIONS in vrača permisivne glave CORS (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), tako da je A2A mogoče klicati iz orkestratorjev v brskalniku brez proxyja.