Magisterium AI

Żviluppaturi
Aqsam:

Kif Tibda

Din il-gwida tgħaddik mill-għamil tal-ewwel talba tiegħek lill-endpoint A2A ta' Magisterium, l-irkupru tax-xogħol li jirriżulta, u l-qari tar-rispons strutturat.

Prerekwiżiti

  1. Pjan Magisterium imħallas (Pro, Organizzazzjoni, jew Enterprise). Il-kontijiet b'xejn jirċievu żball PLAN_REQUIRED minn A2A.
  2. Access token OAuth 2.0 marbut mal-kont magisterium.com tiegħek. A2A juża l-istess fluss OAuth bħas-server MCP tal-Magisterium; skopri l-endpoints tal-awtorizzazzjoni, tat-token, u tar-reġistrazzjoni dinamika mill-metadata OAuth fuq https://www.magisterium.com/.well-known/oauth-authorization-server.
  3. L-iskills li trid issejjaħ — ara Skills għal-lista sħiħa.

Attenzjoni: iċ-ċwievet API twal fiż-żmien maħluqa fl-API Console jaħdmu għal Chat Completions, Search, u News, iżda mhumiex validi għal A2A — A2A jaċċetta biss tokens tal-utent maħruġa permezz ta' OAuth.

Esporta l-access token tiegħek bħala varjabbli tal-ambjent sabiex l-eżempji hawn taħt jieħduh awtomatikament:

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

Pass 1: Skopri l-Aġent

Qabel ma ssejjaħ l-endpoint, tista' tiġbed l-Agent Card pubblika biex tara liema skills huma disponibbli u tikkonferma l-verżjoni tal-protokoll:

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

Il-karta ma teħtieġ l-ebda awtentikazzjoni. L-orkestraturi jistgħu jżommuha fil-cache għal siegħa — l-endpoint jissettja Cache-Control: public, max-age=3600.

Pass 2: Ibgħat l-Ewwel Messaġġ Tiegħek

L-operazzjonijiet kollha A2A jgħaddu minn endpoint JSON-RPC wieħed: POST https://www.magisterium.com/api/v1/a2a. L-eżempju hawn taħt isejjaħ message/send fuq l-iskill 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"])

Pass 3: Aqra r-Rispons

message/send jagħti lura oġġett Task b'kind: "task". Sejħa sinkrona ta' skill dejjem tispiċċa f'wieħed minn żewġ stati terminali:

  • status.state == "completed" — ir-riżultati jinsabu f'result.artifacts. Kull artifact għandu artifactId, name opzjonali, u waħda jew aktar parts (text, data, jew file).
  • status.state == "failed" — ir-raġuni tal-falliment tinsab f'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": [] } }
        ]
      }
    ]
  }
}

Pass 4: Iġbor jew Ikkanċella Xogħol

Ix-xogħlijiet jinħażnu għal 24 siegħa u jistgħu jerġgħu jinġibu bl-ID billi tuża 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" }
    }'

Jekk għandek bżonn taqta' xogħol, sejjaħ tasks/cancel bl-istess ID. Minħabba li l-iskills kollha ta' Magisterium jsolvu b'mod sinkronu, il-kanċellazzjoni hija biss utli f'xenarji rari ta' retry — xogħol li diġà huwa completed jew failed ma jistax jiġi kkanċellat u jagħti lura INVALID_PARAMS.

Żbalji Komuni

KodiċiTifsiraSoluzzjoni
-32004UnauthorizedIċċekkja l-header Authorization u li t-token tal-aċċess huwa validu u mhux skadut.
-32005Pjan imħallas meħtieġAġġorna l-kont tiegħek fuq magisterium.com/plan.
-32002Skill ma nstabxIvverifika li metadata.skillId jaqbel ma' ID elenkat fl-Agent Card.
-32003Limitu tar-rate maqbużStenna retryAfter sekondi (preżenti fil-data tal-iżball) qabel ma terġa' tipprova.

Ara r-Referenza API sħiħa għal kull metodu u kodiċi ta' żball.