Magisterium AI

Pengembang
Bagikan:

Memulai

Panduan ini memandu Anda membuat permintaan pertama ke endpoint A2A Magisterium, mengambil tugas yang dihasilkan, dan membaca respons terstruktur.

Prasyarat

  1. Paket Magisterium berbayar (Pro, Organisasi, atau Perusahaan). Akun gratis akan menerima error PLAN_REQUIRED dari A2A.
  2. Access token OAuth 2.0 yang terikat ke akun magisterium.com Anda. A2A menggunakan alur OAuth yang sama dengan server Magisterium MCP; temukan endpoint otorisasi, token, dan pendaftaran dinamis dari metadata OAuth di https://www.magisterium.com/.well-known/oauth-authorization-server.
  3. Keterampilan yang ingin Anda panggil — lihat Keterampilan untuk daftar lengkap.

Perhatian: kunci API berumur panjang yang dibuat di API Console berfungsi untuk Chat Completions, Search, dan News, tetapi tidak valid untuk A2A — A2A hanya menerima token pengguna yang diterbitkan OAuth.

Ekspor access token Anda sebagai variabel lingkungan sehingga contoh di bawah ini mengambilnya secara otomatis:

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

Langkah 1: Temukan Agen

Sebelum memanggil endpoint, Anda dapat mengambil Agent Card publik untuk melihat keterampilan mana yang tersedia dan mengonfirmasi versi protokol:

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

Kartu ini tidak memerlukan autentikasi. Orkestrator dapat men-cache-nya selama satu jam — endpoint menetapkan Cache-Control: public, max-age=3600.

Langkah 2: Kirim Pesan Pertama Anda

Semua operasi A2A berjalan melalui satu endpoint JSON-RPC: POST https://www.magisterium.com/api/v1/a2a. Contoh di bawah memanggil message/send pada keterampilan catholic_qa.

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"])

Langkah 3: Membaca Respons

message/send mengembalikan objek Task dengan kind: "task". Panggilan keterampilan sinkron selalu berakhir di salah satu dari dua status terminal:

  • status.state == "completed" — hasilnya ada di result.artifacts. Setiap artifact memiliki artifactId, name opsional, dan satu atau lebih parts (text, data, atau file).
  • status.state == "failed" — alasan kegagalan ada di status.message.parts[0].text.
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": [] } }
        ]
      }
    ]
  }
}

Langkah 4: Mengambil atau Membatalkan Tugas

Tugas disimpan selama 24 jam dan dapat diambil ulang berdasarkan ID menggunakan tasks/get:

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" }
    }'

Jika Anda perlu membatalkan tugas, panggil tasks/cancel dengan ID yang sama. Karena semua keterampilan Magisterium diselesaikan secara sinkron, pembatalan hanya berguna dalam skenario percobaan ulang yang jarang — tugas yang sudah completed atau failed tidak dapat dibatalkan dan akan mengembalikan INVALID_PARAMS.

Error Umum

KodeArtiPerbaikan
-32004Tidak diautentikasiPeriksa header Authorization dan pastikan access token valid dan belum kedaluwarsa.
-32005Memerlukan paket berbayarTingkatkan akun Anda di magisterium.com/plan.
-32002Keterampilan tidak ditemukanVerifikasi metadata.skillId cocok dengan ID yang terdaftar di Agent Card.
-32003Batas laju terlampauiTunggu retryAfter detik (ada di data error) sebelum mencoba lagi.

Lihat Referensi API lengkap untuk setiap metode dan kode error.