Բոլոր մեթոդները կանչվում են POST-ով https://www.magisterium.com/api/v1/a2a հասցեով՝ օգտագործելով JSON-RPC 2.0։ Յուրաքանչյուր հարցում պետք է ներառի Authorization: Bearer $MAGISTERIUM_TOKEN (OAuth-ի կողմից տրված օգտատիրոջ թոքեն — տե՛ս Որակավորում) և Content-Type: application/json։

Մեթոդներ

message/send

Ուղարկեք հաղորդագրություն հմտությանը և ստացեք ավարտված առաջադրանք։ Magisterium-ի բոլոր հմտությունները սինխրոն են — պատասխանը պարունակում է տերմինալ առաջադրանքի վիճակը (completed կամ failed), երբեք ոչ միջանկյալ working կարգավիճակ։

Պարամետրեր.

Դաշտ	Տեսակ	Պարտադիր	Նկարագրություն
message	Message	Այո	Օգտագործողի հաղորդագրություն՝ part-երով և ընտրովի մետատվյալներով։
message.role	string	Այո	Պետք է լինի "user"։
message.messageId	string	Այո	Այս հաղորդագրության եզակի ID։
message.kind	string	Այո	Պետք է լինի "message"։
message.parts	Part[]	Այո	Առնվազն մեկ part (տեքստ կամ տվյալ)։
message.metadata.skillId	string	Ոչ	Կանչվելիք հմտությունը։ Լռելյայն՝ catholic_qa։
message.contextId	string	Ոչ	Ընտրովի context ID՝ կապակցված առաջադրանքները խմբավորելու համար։ Եթե բացթողված է, սերվերը ստեղծում է։
configuration	object	Ոչ	Պահված է ապագա օգտագործման համար։

Վերադարձնում է. Task օբյեկտ՝ kind: "task"-ով։

tasks/get

Ստացեք նախկինում ստեղծված առաջադրանքը իր ID-ով։

Պարամետրեր.

Դաշտ	Տեսակ	Պարտադիր	Նկարագրություն
id	string	Այո	message/send-ից վերադարձված առաջադրանքի ID։

Վերադարձնում է. Task օբյեկտը կամ TASK_NOT_FOUND սխալ, եթե ժամկետանց է կամ բացակայում է։ Առաջադրանքները պահվում են 24 ժամ։

tasks/cancel

Չեղարկեք առաջադրանքը, եթե այն գտնվում է չեղարկելի վիճակում։ Քանի որ բոլոր հմտությունները լուծվում են սինխրոն, պատասխանը վերադառնալու պահին առաջադրանքների մեծ մասն արդեն գտնվում է տերմինալ վիճակում (completed / failed) — տերմինալ առաջադրանքը չեղարկելու փորձը վերադարձնում է INVALID_PARAMS հաղորդագրությամբ՝ Invalid state transition։

Պարամետրեր.

Դաշտ	Տեսակ	Պարտադիր	Նկարագրություն
id	string	Այո	Չեղարկելիք առաջադրանքի ID։

Վերադարձնում է. Թարմացված Task օբյեկտ՝ status.state: "canceled"-ով։

Առաջադրանքի կյանքի ցիկլ

Magisterium-ի հմտությունները աշխատում են սինխրոն, ուստի առաջադրանքը պահոցում պահպանվում է միայն հմտության ավարտից հետո — միշտ տերմինալ վիճակում։ submitted և working վիճակները A2A-ի ավելի լայն բնութագրի մասն են, սակայն Magisterium-ի իրականացման կողմից երբեք չեն ստեղծվում. դուք կարող եք դիտել միայն ստորև ներկայացված երեք տերմինալ վիճակներից մեկը։

Վիճակ	Իմաստ
completed	Տերմինալ — արդյունքները գտնվում են artifacts-ում։ Վերադարձվում է message/send-ի կողմից, երբ հմտությունը հաջողությամբ ավարտվում է։
failed	Տերմինալ — status.message պարունակում է ձախողման պատճառը։ Վերադարձվում է message/send-ի կողմից, երբ հմտությունը նետում է բացառություն։
canceled	Տերմինալ — հասանելի է միայն ոչ տերմինալ առաջադրանքի վրա tasks/cancel կանչելու միջոցով։ Քանի որ message/send-ի վերադարձի պահին առաջադրանքները արդեն տերմինալ վիճակում են, գործնականում ձեր ձեռքի տակ եղած ցանկացած առաջադրանքի համար չեղարկումը մերժվում է INVALID_PARAMS-ով։

Յուրաքանչյուր առաջադրանք նաև կրում է.

• contextId — խմբավորման նույնացուցիչ, որը կարող եք կրկին օգտագործել հետագա հաղորդագրություններում՝ կապակցված առաջադրանքները միացնելու համար։
• history — օգտագործողի և գործակալի հաղորդագրությունների կարգավորված ցանկ, որոնք ստեղծել են առաջադրանքի artifact-ները։

Սխալի կոդեր

Կոդ	Անվանում	Նկարագրություն
-32700	Parse error	Անվավեր JSON մարմին։
-32600	Invalid request	Բացակայում են jsonrpc, method կամ id դաշտերը։
-32601	Method not found	Անհայտ JSON-RPC մեթոդ։
-32602	Invalid params	Բացակայող կամ անվավեր պարամետրեր (վերադարձվում է նաև tasks/cancel-ի անվավեր վիճակի անցումների համար)։
-32603	Internal error	Սերվերի կողմից անսպասելի ձախողում։
-32001	Task not found	Առաջադրանքի ID-ն գոյություն չունի կամ ժամկետանց է։
-32002	Skill not found	Անհայտ skillId հաղորդագրության մետատվյալներում։
-32003	Rate limit exceeded	Շատ հարցումներ։ Ստուգեք retryAfter-ը (վայրկյաններով) սխալի data-ում։
-32004	Unauthorized	Բացակայող կամ անվավեր Bearer թոքեն։
-32005	Paid plan required	A2A-ն պահանջում է Pro, Կազմակերպություն կամ Տնտեսություն պլան։

HTTP կարգավիճակն արտացոլում է սխալի դասը՝ 401 UNAUTHORIZED-ի համար, 403 PLAN_REQUIRED-ի համար, 429 RATE_LIMITED-ի համար և 200 JSON-RPC-ի մյուս բոլոր սխալների համար (JSON-RPC-ի պայմանով՝ վերադարձնել 200 error մարմնով)։

Արագության սահմանաչափեր

A2A-ն կիսում է նույն արագության սահմանաչափի ավազանը MCP-ի հետ — պլանի համար հարցումների վերին սահմանների համար տե՛ս MCP-ի գները։

Կիրառվում են երկու տարբերակ.

• Լռելյայն — կիրառվում է document_search-ի, document_fetch-ի, liturgical_readings-ի և saints_of_the_day-ի համար։
• Թանկ — կիրառվում է միայն catholic_qa-ի համար, քանի որ այն աշխատեցնում է LLM-ի վրա հիմնված պատասխանների հոսք։ Այս տարբերակն օգտագործում է ավելի խիստ, ավելի ցածր սահման։

Երբ հասնում եք սահմանաչափին, սխալի data օբյեկտը պարունակում է retryAfter վայրկյաններով։ Կանչողները պետք է հետ քաշվեն այդ ինտերվալի ընթացքում՝ նախքան կրկին փորձելը։

CORS

Վերջնակետը պատասխանում է OPTIONS preflight հարցումներին և վերադարձնում է թույլատրողական CORS վերնագրեր (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), ուստի A2A-ն կարելի է կանչել բրաուզերի վրա հիմնված համադրիչներից առանց պրոքսիի։