Tüm yöntemler, JSON-RPC 2.0 kullanılarak https://www.magisterium.com/api/v1/a2a adresine POST ile çağrılır. Her istek Authorization: Bearer $MAGISTERIUM_TOKEN (OAuth tarafından verilmiş bir kullanıcı token'ı — bkz. Kimlik Doğrulama) ve Content-Type: application/json içermelidir.

Yöntemler

message/send

Bir yeteneğe mesaj gönderin ve tamamlanmış bir görev alın. Tüm Magisterium yetenekleri senkrondur — yanıt, terminal görev durumunu (completed veya failed) içerir; hiçbir zaman ara bir working durumu içermez.

Params:

Alan	Tür	Zorunlu	Açıklama
message	Message	Evet	Part'lar ve isteğe bağlı meta veriye sahip kullanıcı mesajı.
message.role	string	Evet	"user" olmalıdır.
message.messageId	string	Evet	Bu mesaj için benzersiz ID.
message.kind	string	Evet	"message" olmalıdır.
message.parts	Part[]	Evet	En az bir part (text veya data).
message.metadata.skillId	string	Hayır	Çağrılacak yetenek. Varsayılan: catholic_qa.
message.contextId	string	Hayır	İlgili görevleri gruplamak için isteğe bağlı context ID. Atlanırsa sunucu bir tane üretir.
configuration	object	Hayır	Gelecekteki kullanım için ayrılmıştır.

Dönüş: kind: "task" olan bir Task nesnesi.

tasks/get

Daha önce oluşturulmuş bir görevi ID'sine göre al.

Params:

Alan	Tür	Zorunlu	Açıklama
id	string	Evet	message/send'den dönen görev ID'si.

Dönüş: Task nesnesi veya görev süresi dolmuş ya da eksik ise TASK_NOT_FOUND hatası. Görevler 24 saat boyunca saklanır.

tasks/cancel

Görev iptal edilebilir bir durumdaysa, görevi iptal et. Tüm yetenekler senkron olarak çözüldüğünden, yanıt döndüğünde çoğu görev zaten terminal bir durumdadır (completed / failed) — terminal bir görevi iptal etmeye çalışmak, Invalid state transition mesajı ile birlikte INVALID_PARAMS döndürür.

Params:

Alan	Tür	Zorunlu	Açıklama
id	string	Evet	İptal edilecek görev ID'si.

Dönüş: status.state: "canceled" olan güncellenmiş Task nesnesi.

Görev Yaşam Döngüsü

Magisterium'un yetenekleri senkron olarak çalışır, bu nedenle bir görev yalnızca yetenek tamamlandıktan sonra depoya kalıcı olarak kaydedilir — her zaman terminal bir durumda. submitted ve working durumları, daha geniş A2A spesifikasyonunun bir parçasıdır ancak Magisterium'un uygulaması tarafından hiçbir zaman üretilmez; yalnızca aşağıdaki üç terminal durumdan birini gözlemlersiniz.

Durum	Anlam
completed	Terminal — sonuçlar artifacts içindedir. Yetenek başarıyla tamamlandığında message/send tarafından döndürülür.
failed	Terminal — status.message başarısızlık nedenini içerir. Yetenek bir hata fırlattığında message/send tarafından döndürülür.
canceled	Terminal — yalnızca terminal olmayan bir göreve tasks/cancel çağrılarak ulaşılabilir. Görevler message/send döndüğünde zaten terminal durumda olduğundan, pratikte elinizde tuttuğunuz herhangi bir görev için iptal INVALID_PARAMS ile reddedilir.

Her görev ayrıca şunları taşır:

• contextId — ilgili görevleri bağlamak için sonraki mesajlarda yeniden kullanabileceğiniz bir gruplama tanımlayıcısı.
• history — görevin artifact'larını üreten kullanıcı ve ajan mesajlarının sıralı listesi.

Hata Kodları

Kod	Ad	Açıklama
-32700	Parse error	Geçersiz JSON gövdesi.
-32600	Invalid request	Eksik jsonrpc, method veya id alanları.
-32601	Method not found	Bilinmeyen JSON-RPC yöntemi.
-32602	Invalid params	Eksik veya geçersiz parametreler (geçersiz tasks/cancel durum geçişleri için de döner).
-32603	Internal error	Beklenmeyen sunucu tarafı hatası.
-32001	Task not found	Görev ID'si mevcut değil veya süresi dolmuş.
-32002	Skill not found	Mesaj meta verisinde bilinmeyen skillId.
-32003	Rate limit exceeded	Çok fazla istek. Hata data içindeki retryAfter'ı (saniye) kontrol edin.
-32004	Unauthorized	Eksik veya geçersiz Bearer token.
-32005	Paid plan required	A2A, Pro, Organizasyon veya Kurumsal plan gerektirir.

HTTP durumu hata sınıfını yansıtır: UNAUTHORIZED için 401, PLAN_REQUIRED için 403, RATE_LIMITED için 429 ve diğer tüm JSON-RPC hataları için 200 (JSON-RPC sözleşmesine göre error gövdesiyle birlikte 200 döndürmek).

Hız Limitleri

A2A, MCP ile aynı hız limiti havuzunu paylaşır — plan başına istek üst sınırları için MCP Fiyatlandırma bölümüne bakın.

İki varyant uygulanır:

• Varsayılan — document_search, document_fetch, liturgical_readings ve saints_of_the_day için geçerlidir.
• Pahalı — yalnızca catholic_qa için geçerlidir; çünkü LLM destekli bir yanıt pipeline'ı çalıştırır. Bu varyant daha sıkı, daha düşük bir üst sınır kullanır.

Bir limite ulaştığınızda, hata data nesnesi saniye cinsinden bir retryAfter içerir. Arayanların yeniden denemeden önce o aralık boyunca geri çekilmesi gerekir.

CORS

Uç nokta OPTIONS preflight isteklerine yanıt verir ve müsamahakâr CORS başlıkları (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization) döndürür; böylece A2A, proksi olmadan tarayıcı tabanlı orkestratörlerden çağrılabilir.