Sve metode se pozivaju putem POST na https://www.magisterium.com/api/v1/a2a koristeći JSON-RPC 2.0. Svaki zahtjev mora uključivati Authorization: Bearer $MAGISTERIUM_TOKEN (korisnički token izdan putem OAutha — vidi Autentifikaciju) i Content-Type: application/json.

Metode

message/send

Pošaljite poruku vještini i primite dovršeni zadatak. Sve Magisterium vještine su sinkrone — odgovor sadrži terminalno stanje zadatka (completed ili failed), nikada međustanje working.

Parametri:

Polje	Tip	Obavezno	Opis
message	Message	Da	Korisnikova poruka s dijelovima i opcionalnim metapodacima.
message.role	string	Da	Mora biti "user".
message.messageId	string	Da	Jedinstveni ID za ovu poruku.
message.kind	string	Da	Mora biti "message".
message.parts	Part[]	Da	Najmanje jedan dio (text ili data).
message.metadata.skillId	string	Ne	Vještina za pozivanje. Zadano je catholic_qa.
message.contextId	string	Ne	Opcionalni ID konteksta za grupiranje povezanih zadataka. Ako je izostavljen, poslužitelj će ga generirati.
configuration	object	Ne	Rezervirano za buduću upotrebu.

Vraća: Objekt Task s kind: "task".

tasks/get

Dohvatite prethodno stvoreni zadatak prema njegovom ID-u.

Parametri:

Polje	Tip	Obavezno	Opis
id	string	Da	ID zadatka vraćen iz message/send.

Vraća: Objekt Task ili pogrešku TASK_NOT_FOUND ako je istekao ili nedostaje. Zadaci se pohranjuju 24 sata.

tasks/cancel

Otkažite zadatak ako je u stanju koje dopušta otkazivanje. Budući da se sve vještine izvršavaju sinkrono, većina zadataka je već u terminalnom stanju (completed / failed) u trenutku kada se odgovor vrati — pokušaj otkazivanja terminalnog zadatka vraća INVALID_PARAMS s porukom Invalid state transition.

Parametri:

Polje	Tip	Obavezno	Opis
id	string	Da	ID zadatka koji se otkazuje.

Vraća: Ažurirani objekt Task sa status.state: "canceled".

Životni ciklus zadatka

Vještine Magisteriuma izvršavaju se sinkrono, pa se zadatak pohranjuje tek nakon što vještina završi — uvijek u terminalnom stanju. Stanja submitted i working dio su šire A2A specifikacije, ali ih implementacija Magisteriuma nikada ne proizvodi; uvijek ćete vidjeti samo jedno od tri terminalna stanja u nastavku.

Stanje	Značenje
completed	Terminalno — rezultati su u artifacts. Vraća ga message/send kada vještina uspješno završi.
failed	Terminalno — status.message sadrži razlog neuspjeha. Vraća ga message/send kada vještina baci iznimku.
canceled	Terminalno — dostižno samo pozivom tasks/cancel na neterminalnom zadatku. Budući da su zadaci već u terminalnom stanju u trenutku kada se message/send vraća, u praksi se otkazivanje odbija s INVALID_PARAMS za bilo koji zadatak na koji imate referencu.

Svaki zadatak također nosi:

• contextId — identifikator grupiranja koji možete ponovno koristiti u nastavnim porukama za povezivanje srodnih zadataka.
• history — uređeni popis poruka korisnika i agenta koje su proizvele artefakte zadatka.

Kodovi pogrešaka

Kod	Naziv	Opis
-32700	Parse error	Nevažeće JSON tijelo.
-32600	Invalid request	Nedostaju polja jsonrpc, method ili id.
-32601	Method not found	Nepoznata JSON-RPC metoda.
-32602	Invalid params	Nedostajući ili nevaljani parametri (također se vraća za nevaljane prijelaze stanja tasks/cancel).
-32603	Internal error	Neočekivani kvar na strani poslužitelja.
-32001	Task not found	ID zadatka ne postoji ili je istekao.
-32002	Skill not found	Nepoznat skillId u metapodacima poruke.
-32003	Rate limit exceeded	Previše zahtjeva. Provjerite retryAfter (sekunde) u data pogreške.
-32004	Unauthorized	Nedostajući ili nevaljani Bearer token.
-32005	Paid plan required	A2A zahtijeva plan Pro, Organization ili Enterprise.

HTTP status odražava klasu pogreške: 401 za UNAUTHORIZED, 403 za PLAN_REQUIRED, 429 za RATE_LIMITED i 200 za sve ostale JSON-RPC pogreške (prema JSON-RPC konvenciji vraćanja 200 s tijelom error).

Ograničenja zahtjeva

A2A dijeli isti bazen ograničenja zahtjeva kao MCP — pogledajte Cijene MCP-a za ograničenja zahtjeva po planu.

Provode se dvije varijante:

• Default — primjenjuje se na document_search, document_fetch, liturgical_readings i saints_of_the_day.
• Expensive — primjenjuje se samo na catholic_qa, jer izvršava cjevovod odgovora temeljen na LLM-u. Ova varijanta koristi strože, niže ograničenje.

Kada dosegnete ograničenje, objekt data pogreške sadrži retryAfter u sekundama. Pozivatelji bi se trebali povući za taj interval prije ponovnog pokušaja.

CORS

Endpoint odgovara na preflight zahtjeve OPTIONS i vraća popustljive CORS zaglavlja (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), tako da se A2A može pozivati iz orkestratora u pregledniku bez proxyja.