Il-metodi kollha jiġu msejħa permezz ta' POST lil https://www.magisterium.com/api/v1/a2a billi jużaw JSON-RPC 2.0. Kull talba trid tinkludi Authorization: Bearer $MAGISTERIUM_TOKEN (token tal-utent maħruġ permezz ta' OAuth — ara Awtentikazzjoni) u Content-Type: application/json.

Metodi

message/send

Ibgħat messaġġ lil skill u irċievi xogħol komplut. L-iskills kollha ta' Magisterium huma sinkroni — ir-rispons fih l-istat terminali tax-xogħol (completed jew failed), qatt status intermedju working.

Params:

Kamp	Tip	Meħtieġ	Deskrizzjoni
message	Message	Iva	Il-messaġġ tal-utent b'partijiet u metadata opzjonali.
message.role	string	Iva	Irid ikun "user".
message.messageId	string	Iva	ID uniku għal dan il-messaġġ.
message.kind	string	Iva	Irid ikun "message".
message.parts	Part[]	Iva	Mill-anqas parti waħda (text jew data).
message.metadata.skillId	string	Le	Skill li tiġi msejħa. Id-default huwa catholic_qa.
message.contextId	string	Le	ID tal-kuntest opzjonali biex jiġbor flimkien xogħlijiet relatati. Jekk jitħalla barra, is-server jiġġenera wieħed.
configuration	object	Le	Riservat għal użu futur.

Jagħti lura: Oġġett Task b'kind: "task".

tasks/get

Iġbor xogħol maħluq qabel bl-ID tiegħu.

Params:

Kamp	Tip	Meħtieġ	Deskrizzjoni
id	string	Iva	L-ID tax-xogħol mogħti lura minn message/send.

Jagħti lura: L-oġġett Task, jew żball TASK_NOT_FOUND jekk skada jew huwa nieqes. Ix-xogħlijiet jinħażnu għal 24 siegħa.

tasks/cancel

Ikkanċella xogħol jekk huwa fi stat li jista' jiġi kkanċellat. Minħabba li l-iskills kollha jsolvu b'mod sinkronu, il-biċċa l-kbira tax-xogħlijiet huma diġà fi stat terminali (completed / failed) meta r-rispons jirritorna — tentattiv biex tikkanċella xogħol terminali jagħti lura INVALID_PARAMS b'messaġġ Invalid state transition.

Params:

Kamp	Tip	Meħtieġ	Deskrizzjoni
id	string	Iva	L-ID tax-xogħol biex jiġi kkanċellat.

Jagħti lura: L-oġġett Task aġġornat b'status.state: "canceled".

Ċiklu tal-Ħajja tax-Xogħol

L-iskills ta' Magisterium jaħdmu b'mod sinkronu, allura xogħol jiġi ppersistit fil-ħażna biss wara li l-iskill tlesti — dejjem fi stat terminali. L-istati submitted u working huma parti mill-ispeċifikazzjoni A2A usa', iżda qatt ma jiġu prodotti mill-implementazzjoni ta' Magisterium; int dejjem se tosserva biss wieħed mit-tliet stati terminali ta' hawn taħt.

Stat	Tifsira
completed	Terminali — ir-riżultati jinsabu f'artifacts. Mogħti lura minn message/send meta l-iskill tlesti b'suċċess.
failed	Terminali — status.message fiha r-raġuni tal-falliment. Mogħti lura minn message/send meta l-iskill tarmi eċċezzjoni.
canceled	Terminali — jintlaħaq biss billi tissejjaħ tasks/cancel fuq xogħol mhux terminali. Minħabba li x-xogħlijiet ikunu diġà terminali sa meta message/send jirritorna, fil-prattika l-kanċellazzjoni tiġi rrifjutata b'INVALID_PARAMS għal kwalunkwe xogħol li għandek handle tiegħu.

Kull xogħol iġorr ukoll:

• contextId — identifikatur ta' gruppjar li tista' terġa' tuża fuq messaġġi segwenti biex torbot xogħlijiet relatati.
• history — il-lista ordnata ta' messaġġi tal-utent u tal-aġent li pproduċew l-artifacts tax-xogħol.

Kodiċi tal-Iżbalji

Kodiċi	Isem	Deskrizzjoni
-32700	Parse error	Korp JSON invalidu.
-32600	Invalid request	Kampi jsonrpc, method, jew id neqsin.
-32601	Method not found	Metodu JSON-RPC mhux magħruf.
-32602	Invalid params	Parametri neqsin jew invalidi (jingħata lura wkoll għal tranżizzjonijiet ta' stat invalidi ta' tasks/cancel).
-32603	Internal error	Falliment mhux mistenni min-naħa tas-server.
-32001	Task not found	L-ID tax-xogħol ma jeżistix jew skada.
-32002	Skill not found	skillId mhux magħruf fil-metadata tal-messaġġ.
-32003	Rate limit exceeded	Wisq talbiet. Iċċekkja retryAfter (sekondi) fil-data tal-iżball.
-32004	Unauthorized	Token Bearer nieqes jew invalidu.
-32005	Paid plan required	A2A jeħtieġ pjan Pro, Organizzazzjoni, jew Enterprise.

L-istatus HTTP jirrifletti l-klassi tal-iżball: 401 għal UNAUTHORIZED, 403 għal PLAN_REQUIRED, 429 għal RATE_LIMITED, u 200 għall-iżbalji JSON-RPC l-oħra kollha (skont il-konvenzjoni JSON-RPC li jingħata lura 200 b'korp error).

Limiti tar-Rate

A2A jaqsam l-istess pool tar-rate-limit bħal MCP — ara Prezzijiet MCP għal-limiti ta' talbiet għal kull pjan.

Żewġ varjanti jiġu infurzati:

• Default — tapplika għal document_search, document_fetch, liturgical_readings, u saints_of_the_day.
• Expensive — tapplika għal catholic_qa biss, peress li ddur pipeline ta' risposta bbażata fuq LLM. Din il-varjanta tuża limitu aktar strett u aktar baxx.

Meta tilħaq limitu, l-oġġett data tal-iżball fih retryAfter f'sekondi. Min isejjaħ għandu jagħmel back-off għal dan l-intervall qabel ma jerġa' jipprova.

CORS

L-endpoint iwieġeb għal talbiet ta' preflight OPTIONS u jagħti lura headers CORS permissivi (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), sabiex A2A jista' jiġi msejjaħ minn orkestraturi bbażati fuq il-browser mingħajr proxy.