সমস্ত পদ্ধতি JSON-RPC 2.0 ব্যবহার করে https://www.magisterium.com/api/v1/a2a-তে POST-এর মাধ্যমে কল করা হয়। প্রতিটি অনুরোধে অবশ্যই Authorization: Bearer $MAGISTERIUM_TOKEN (একটি OAuth দ্বারা জারি করা ব্যবহারকারী টোকেন — প্রমাণীকরণ দেখুন) এবং Content-Type: application/json অন্তর্ভুক্ত থাকতে হবে।

পদ্ধতি

message/send

একটি দক্ষতায় একটি বার্তা পাঠান এবং একটি সম্পন্ন কাজ পান। সমস্ত Magisterium দক্ষতা সিঙ্ক্রোনাস — প্রতিক্রিয়াটিতে টার্মিনাল কাজের অবস্থা (completed বা failed) থাকে, কখনো কোনো মধ্যবর্তী working স্ট্যাটাস নয়।

প্যারামিটার:

ফিল্ড	প্রকার	আবশ্যক	বিবরণ
message	Message	হ্যাঁ	অংশ এবং ঐচ্ছিক মেটাডেটা সহ ব্যবহারকারী বার্তা।
message.role	string	হ্যাঁ	অবশ্যই "user" হতে হবে।
message.messageId	string	হ্যাঁ	এই বার্তার জন্য অনন্য ID।
message.kind	string	হ্যাঁ	অবশ্যই "message" হতে হবে।
message.parts	Part[]	হ্যাঁ	কমপক্ষে একটি অংশ (টেক্সট বা ডেটা)।
message.metadata.skillId	string	না	আহ্বান করার জন্য দক্ষতা। ডিফল্ট catholic_qa।
message.contextId	string	না	সম্পর্কিত কাজগুলি গ্রুপ করার জন্য ঐচ্ছিক প্রসঙ্গ ID। যদি বাদ দেওয়া হয়, সার্ভার একটি তৈরি করে।
configuration	object	না	ভবিষ্যতের ব্যবহারের জন্য সংরক্ষিত।

ফেরত দেয়: kind: "task" সহ একটি Task অবজেক্ট।

tasks/get

পূর্বে তৈরি করা একটি কাজ তার ID দ্বারা পুনরুদ্ধার করুন।

প্যারামিটার:

ফিল্ড	প্রকার	আবশ্যক	বিবরণ
id	string	হ্যাঁ	message/send থেকে ফেরত দেওয়া কাজ ID।

ফেরত দেয়: Task অবজেক্ট, বা যদি মেয়াদ শেষ হয়ে যায় বা অনুপস্থিত থাকে তবে একটি TASK_NOT_FOUND ত্রুটি। কাজগুলি 24 ঘণ্টা এর জন্য সংরক্ষিত থাকে।

tasks/cancel

একটি কাজ বাতিলযোগ্য অবস্থায় থাকলে এটি বাতিল করুন। যেহেতু সমস্ত দক্ষতা সিঙ্ক্রোনাস ভাবে সমাধান হয়, বেশিরভাগ কাজ প্রতিক্রিয়া ফেরত আসার সময়ের মধ্যে ইতিমধ্যে একটি টার্মিনাল অবস্থায় (completed / failed) থাকে — একটি টার্মিনাল কাজ বাতিল করার চেষ্টা একটি Invalid state transition বার্তা সহ INVALID_PARAMS ফেরত দেয়।

প্যারামিটার:

ফিল্ড	প্রকার	আবশ্যক	বিবরণ
id	string	হ্যাঁ	বাতিল করার জন্য কাজ ID।

ফেরত দেয়: status.state: "canceled" সহ আপডেট করা Task অবজেক্ট।

কাজের জীবনচক্র

Magisterium-এর দক্ষতাগুলি সিঙ্ক্রোনাসভাবে চলে, তাই দক্ষতা শেষ হওয়ার পরেই কাজটি স্টোরেজে সংরক্ষিত হয় — সর্বদা একটি টার্মিনাল অবস্থায়। submitted এবং working অবস্থাগুলি বৃহত্তর A2A স্পেসিফিকেশনের অংশ হলেও Magisterium-এর বাস্তবায়ন এগুলি কখনোই উৎপন্ন করে না; আপনি কেবল নিচের তিনটি টার্মিনাল অবস্থার একটিই দেখতে পাবেন।

অবস্থা	অর্থ
completed	টার্মিনাল — ফলাফল artifacts-এ থাকে। দক্ষতা সফলভাবে শেষ হলে message/send ফেরত দেয়।
failed	টার্মিনাল — status.message-এ ব্যর্থতার কারণ থাকে। দক্ষতা ব্যতিক্রম ছুঁড়লে message/send ফেরত দেয়।
canceled	টার্মিনাল — শুধুমাত্র অ-টার্মিনাল কাজে tasks/cancel কল করলেই পৌঁছানো যায়। যেহেতু message/send ফেরত আসার সময়ই কাজগুলি ইতিমধ্যেই টার্মিনাল অবস্থায় থাকে, বাস্তবে আপনার হাতে থাকা যেকোনো কাজের জন্য বাতিলকরণ INVALID_PARAMS দিয়ে প্রত্যাখ্যাত হয়।

প্রতিটি কাজ বহন করে:

• contextId — একটি গ্রুপিং শনাক্তকারী যা আপনি সম্পর্কিত কাজগুলি লিঙ্ক করতে ফলো-আপ বার্তাগুলিতে পুনঃব্যবহার করতে পারেন।
• history — ব্যবহারকারী এবং এজেন্ট বার্তাগুলির ক্রমানুসারে তালিকা যা কাজের আর্টিফ্যাক্টগুলি তৈরি করেছে।

ত্রুটি কোড

কোড	নাম	বিবরণ
-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	অনেক বেশি অনুরোধ। ত্রুটির data-এ retryAfter (সেকেন্ড) পরীক্ষা করুন।
-32004	Unauthorized	অনুপস্থিত বা অবৈধ Bearer টোকেন।
-32005	Paid plan required	A2A-এর জন্য Pro, Organization, বা Enterprise প্ল্যান প্রয়োজন।

HTTP স্ট্যাটাস ত্রুটি শ্রেণীর প্রতিফলন করে: UNAUTHORIZED-এর জন্য 401, PLAN_REQUIRED-এর জন্য 403, RATE_LIMITED-এর জন্য 429, এবং অন্যান্য সমস্ত JSON-RPC ত্রুটির জন্য 200 (JSON-RPC কনভেনশন অনুযায়ী একটি error বডি সহ 200 ফেরত দেওয়া)।

রেট সীমা

A2A MCP-এর সাথে একই রেট-লিমিট পুল শেয়ার করে — প্রতি-প্ল্যান অনুরোধের সীমার জন্য MCP মূল্য নির্ধারণ দেখুন।

দুটি ভ্যারিয়েন্ট প্রয়োগ করা হয়:

• ডিফল্ট — document_search, document_fetch, liturgical_readings, এবং saints_of_the_day-এ প্রযোজ্য।
• ব্যয়বহুল — শুধুমাত্র catholic_qa-এ প্রযোজ্য, কারণ এটি একটি LLM-সমর্থিত উত্তর পাইপলাইন চালায়। এই ভ্যারিয়েন্টটি একটি কঠোর, নিম্ন সীমা ব্যবহার করে।

আপনি যখন একটি সীমায় পৌঁছান, ত্রুটির data অবজেক্টে সেকেন্ডে retryAfter থাকে। কলকারীদের পুনরায় চেষ্টা করার আগে সেই ব্যবধানের জন্য পিছিয়ে যেতে হবে।

CORS

এন্ডপয়েন্টটি OPTIONS প্রিফ্লাইট অনুরোধগুলিতে সাড়া দেয় এবং অনুমতিযোগ্য CORS হেডার ফেরত দেয় (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), তাই A2A একটি প্রক্সি ছাড়াই ব্রাউজার-ভিত্তিক অর্কেস্ট্রেটর থেকে কল করা যেতে পারে।