Magisterium AI

Razvijalci
Deli:

Začetek

Ta vodnik vas popelje skozi ustvarjanje prve zahteve do končne točke Magisterium A2A, pridobivanje nastale naloge in branje strukturiranega odziva.

Predpogoji

  1. Plačljiv načrt Magisterium (Pro, Organization ali Enterprise). Brezplačni računi bodo od A2A prejeli napako PLAN_REQUIRED.
  2. Dostopni žeton OAuth 2.0, vezan na vaš račun magisterium.com. A2A uporablja enak OAuth tok kot strežnik Magisterium MCP; avtorizacijsko končno točko, končno točko za žeton in končno točko dinamične registracije odjemalca najdete v metapodatkih OAuth na https://www.magisterium.com/.well-known/oauth-authorization-server.
  3. Veščine, ki jih želite klicati — celoten seznam si oglejte v Veščine.

Pozor: dolgotrajni API ključi, ustvarjeni v API Console, delujejo za Chat Completions, Search in News, vendar niso veljavni za A2A — A2A sprejema le uporabniške žetone, izdane prek OAuth.

Izvozite svoj dostopni žeton kot spremenljivko okolja, da jo bodo spodnji primeri samodejno prevzeli:

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

Korak 1: Odkrijte agenta

Preden pokličete končno točko, lahko prenesete javno Agent Card, da vidite, katere veščine so na voljo, in potrdite različico protokola:

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

Kartica ne zahteva avtentifikacije. Orkestratorji jo lahko predpomnijo za eno uro — končna točka nastavi Cache-Control: public, max-age=3600.

Korak 2: Pošljite svoje prvo sporočilo

Vse operacije A2A gredo skozi eno JSON-RPC končno točko: POST https://www.magisterium.com/api/v1/a2a. Spodnji primer kliče message/send na veščini 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"])

Korak 3: Preberite odziv

message/send vrne objekt Task z kind: "task". Sinhroni klic veščine se vedno konča v enem od dveh terminalnih stanj:

  • status.state == "completed" — rezultati so v result.artifacts. Vsak artefakt ima artifactId, neobvezen name in enega ali več parts (text, data ali file).
  • status.state == "failed" — razlog neuspeha je v 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": [] } }
        ]
      }
    ]
  }
}

Korak 4: Pridobitev ali preklic naloge

Naloge so shranjene 24 ur in jih lahko ponovno pridobite po ID z uporabo 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" }
    }'

Če morate nalogo prekiniti, pokličite tasks/cancel z istim ID. Ker se vse veščine Magisterium razrešijo sinhrono, je preklic uporaben le v redkih primerih ponavljanja — naloge, ki je že completed ali failed, ni mogoče preklicati in bo vrnila INVALID_PARAMS.

Pogoste napake

KodaPomenRešitev
-32004NeavtoriziranoPreverite glavo Authorization in ali je dostopni žeton veljaven in ni potekel.
-32005Potreben plačljiv načrtPosodobite svoj račun na magisterium.com/plan.
-32002Veščina ni najdenaPreverite, da metadata.skillId ustreza ID-ju s seznama v Agent Card.
-32003Presežena omejitev zahtevPred ponovnim poskusom počakajte retryAfter sekund (prisotno v data napake).

Oglejte si celotno API Referenco za vse metode in kode napak.