Magisterium AI

Geliştiriciler
Paylaş:

Başlarken

Bu kılavuz, Magisterium A2A uç noktasına ilk isteğinizi yapma, oluşturulan görevi alma ve yapılandırılmış yanıtı okuma adımlarında size rehberlik eder.

Ön Koşullar

  1. Ücretli bir Magisterium planı (Pro, Organizasyon veya Kurumsal). Ücretsiz hesaplar A2A'dan PLAN_REQUIRED hatası alır.
  2. magisterium.com hesabınıza bağlı bir OAuth 2.0 erişim token'ı. A2A, Magisterium MCP sunucusu ile aynı OAuth akışını kullanır; yetkilendirme, token ve dinamik kayıt uç noktalarını https://www.magisterium.com/.well-known/oauth-authorization-server adresindeki OAuth meta verilerinden keşfedin.
  3. Çağırmak istediğiniz yetenekler — tam liste için Yetenekler sayfasına bakın.

Dikkat: API Konsolu'nda oluşturulan uzun ömürlü API anahtarları Chat Completions, Search ve News için çalışır, ancak A2A için geçerli değildir — A2A yalnızca OAuth tarafından verilmiş kullanıcı token'larını kabul eder.

Erişim token'ınızı ortam değişkeni olarak dışa aktarın, böylece aşağıdaki örnekler onu otomatik olarak alır:

bash
export MAGISTERIUM_TOKEN=<your-access-token-here>

Adım 1: Ajanı Keşfet

Uç noktayı çağırmadan önce, hangi yeteneklerin mevcut olduğunu görmek ve protokol sürümünü doğrulamak için kamuya açık Agent Card'ı alabilirsiniz:

bash
curl https://www.magisterium.com/.well-known/agent.json

Kart kimlik doğrulama gerektirmez. Orkestratörler onu bir saat boyunca önbelleğe alabilir — uç nokta Cache-Control: public, max-age=3600 ayarını yapar.

Adım 2: İlk Mesajınızı Gönderin

Tüm A2A işlemleri tek bir JSON-RPC uç noktasından geçer: POST https://www.magisterium.com/api/v1/a2a. Aşağıdaki örnek, catholic_qa yeteneği üzerinde message/send'i çağırır.

bash
curl -X POST https://www.magisterium.com/api/v1/a2a \
    -H "Authorization: Bearer $MAGISTERIUM_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "message/send",
      "params": {
        "message": {
          "role": "user",
          "messageId": "msg-001",
          "kind": "message",
          "parts": [{ "kind": "text", "text": "What does the Church teach about the Real Presence?" }],
          "metadata": { "skillId": "catholic_qa" }
        }
      }
    }'
typescript
const accessToken = process.env.MAGISTERIUM_TOKEN!;

const response = await fetch("https://www.magisterium.com/api/v1/a2a", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "message/send",
    params: {
      message: {
        role: "user",
        messageId: crypto.randomUUID(),
        kind: "message",
        parts: [
          { kind: "text", text: "What does the Church teach about the Real Presence?" },
        ],
        metadata: { skillId: "catholic_qa" },
      },
    },
  }),
});

const { result: task } = await response.json();
console.log(task.id, task.status.state);
for (const artifact of task.artifacts ?? []) {
  for (const part of artifact.parts) {
    if (part.kind === "text") console.log(part.text);
  }
}
python
import os
import uuid
import httpx

access_token = os.environ["MAGISTERIUM_TOKEN"]

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
        "message": {
            "role": "user",
            "messageId": str(uuid.uuid4()),
            "kind": "message",
            "parts": [
                {"kind": "text", "text": "What does the Church teach about the Real Presence?"}
            ],
            "metadata": {"skillId": "catholic_qa"},
        }
    },
}

response = httpx.post(
    "https://www.magisterium.com/api/v1/a2a",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
task = response.json()["result"]
print(task["id"], task["status"]["state"])
for artifact in task.get("artifacts", []):
    for part in artifact["parts"]:
        if part["kind"] == "text":
            print(part["text"])

Adım 3: Yanıtı Okuyun

message/send, kind: "task" olan bir Task nesnesi döndürür. Senkron bir yetenek çağrısı her zaman iki terminal durumdan birinde sona erer:

  • status.state == "completed" — sonuçlar result.artifacts içindedir. Her artifact bir artifactId, isteğe bağlı bir name ve bir ya da daha fazla parts (text, data veya file) içerir.
  • status.state == "failed" — başarısızlık nedeni status.message.parts[0].text içindedir.
json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task_abc123",
    "contextId": "ctx_def456",
    "kind": "task",
    "status": { "state": "completed", "timestamp": "2026-04-20T12:00:00.000Z" },
    "artifacts": [
      {
        "artifactId": "art_ghi789",
        "name": "catholic_qa_response",
        "parts": [
          { "kind": "text", "text": "The Catholic Church teaches..." },
          { "kind": "data", "data": { "citations": [] } }
        ]
      }
    ]
  }
}

Adım 4: Bir Görevi Al veya İptal Et

Görevler 24 saat boyunca saklanır ve tasks/get kullanılarak ID ile tekrar alınabilir:

bash
curl -X POST https://www.magisterium.com/api/v1/a2a \
    -H "Authorization: Bearer $MAGISTERIUM_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tasks/get",
      "params": { "id": "task_abc123" }
    }'

Bir görevi iptal etmeniz gerekirse, aynı ID ile tasks/cancel'i çağırın. Tüm Magisterium yetenekleri senkron olarak çözüldüğünden, iptal yalnızca nadir yeniden deneme senaryolarında kullanışlıdır — zaten completed veya failed olan bir görev iptal edilemez ve INVALID_PARAMS döner.

Yaygın Hatalar

KodAnlamıÇözüm
-32004YetkisizAuthorization başlığını ve erişim token'ının geçerli ve süresinin dolmamış olduğunu kontrol edin.
-32005Ücretli plan gerekliHesabınızı magisterium.com/plan adresinden yükseltin.
-32002Yetenek bulunamadımetadata.skillId'nin Agent Card'da listelenen bir ID ile eşleştiğini doğrulayın.
-32003Hız limiti aşıldıYeniden denemeden önce, hatanın data alanında bulunan retryAfter saniye bekleyin.

Tüm yöntemler ve hata kodları için API Referansı'nın tamamına bakın.