Magisterium AI

Evolutores
Communicare Responsum:

Initium

Haec instructio te ducit per primam postulationem ad terminum Magisterii A2A faciendam, munus inde natum recuperandum, et responsum structuratum legendum.

Praerequisita

  1. Consilium Magisterii solvendum (Pro, Organization, vel Enterprise). Rationes liberae errorem PLAN_REQUIRED ex A2A accipient.
  2. Pignus accessus OAuth 2.0 rationi tuae magisterium.com annexum. A2A eodem fluxu OAuth utitur ac serviens Magisterii MCP; inveni terminos auctorizationis, pignoris, et dynamicae inscriptionis ex metadatis OAuth apud https://www.magisterium.com/.well-known/oauth-authorization-server.
  3. Facultates quas invocare vis — vide Facultates pro integro indice.

Animadverte: claves API diuturnae quae in API Console creantur operantur pro Chat Completions, Search, et News, sed non sunt validae pro A2A — A2A solum pignora usuarii per OAuth emissa accipit.

Exporta pignus tuum accessus ut variabilem ambitus ita ut exempla infra eum automatice capiant:

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

Gradus 1: Agentem inveni

Antequam terminum invoces, Chartam Agentis publicam recuperare potes ut videas quae facultates praesto sint et versionem protocolli confirmes:

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

Charta nullam authentificationem requirit. Dispositores eam per horam conservare possunt — terminus Cache-Control: public, max-age=3600 ponit.

Gradus 2: Primum nuntium mitte

Omnes operationes A2A per unum terminum JSON-RPC transeunt: POST https://www.magisterium.com/api/v1/a2a. Exemplum infra message/send in facultate catholic_qa invocat.

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

Gradus 3: Responsum lege

message/send reddit obiectum Task cum kind: "task". Invocatio facultatis synchrona semper in uno ex duobus statibus terminalibus finit:

  • status.state == "completed" — resultata in result.artifacts vivunt. Unumquodque artefactum habet artifactId, name optionale, et unam vel plures parts (text, data, vel file).
  • status.state == "failed" — causa defectus in status.message.parts[0].text est.
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": [] } }
        ]
      }
    ]
  }
}

Gradus 4: Munus recupera aut rescinde

Munera per 24 horas servantur et per ID re-peti possunt utendo 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" }
    }'

Si munus abrumpere opus est, invoca tasks/cancel cum eadem ID. Quia omnes facultates Magisterii synchrone resolvuntur, rescissio solum in rarissimis casibus retentationis utilis est — munus quod iam completed vel failed est rescindi non potest et INVALID_PARAMS reddet.

Errores communes

CodexSignificatioRemedium
-32004UnauthorizedVerifica caput Authorization et signum accessus validum esse nec expiratum.
-32005Consilium solvendum requiriturRationem tuam ad magisterium.com/plan promove.
-32002Facultas non inventaVerifica metadata.skillId concordare cum ID in Charta Agentis enumerata.
-32003Limes rate excessusExspecta retryAfter secunda (praesentia in erroris data) antequam retentes.

Vide integram API Referentiam pro omni methodo et codice erroris.