Magisterium AI

Développeurs
Partager:

Mise en route

Ce guide vous accompagne pour effectuer votre première requête vers le point de terminaison A2A de Magisterium, récupérer la tâche qui en résulte et lire la réponse structurée.

Prérequis

  1. Un plan Magisterium payant (Pro, Organisation ou Entreprise). Les comptes gratuits recevront une erreur PLAN_REQUIRED d'A2A.
  2. Un jeton d'accès OAuth 2.0 lié à votre compte magisterium.com. A2A utilise le même flux OAuth que le serveur MCP Magisterium ; découvrez les points de terminaison d'autorisation, de jeton et d'enregistrement dynamique à partir des métadonnées OAuth disponibles à https://www.magisterium.com/.well-known/oauth-authorization-server.
  3. Les compétences que vous souhaitez appeler — consultez la page Compétences pour la liste complète.

Attention : les clés d'API longue durée créées dans la Console d'API fonctionnent pour Chat Completions, Search et News, mais elles ne sont pas valides pour A2A — A2A n'accepte que des jetons utilisateur émis via OAuth.

Exportez votre jeton d'accès en tant que variable d'environnement afin que les exemples ci-dessous le récupèrent automatiquement :

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

Étape 1 : Découvrir l'agent

Avant d'appeler le point de terminaison, vous pouvez récupérer l'Agent Card publique pour voir quelles compétences sont disponibles et confirmer la version du protocole :

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

La carte ne nécessite aucune authentification. Les orchestrateurs peuvent la mettre en cache pendant une heure — le point de terminaison définit Cache-Control: public, max-age=3600.

Étape 2 : Envoyer votre premier message

Toutes les opérations A2A passent par un unique point de terminaison JSON-RPC : POST https://www.magisterium.com/api/v1/a2a. L'exemple ci-dessous appelle message/send sur la compétence 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"])

Étape 3 : Lire la réponse

message/send renvoie un objet Task avec kind: "task". Un appel synchrone à une compétence se termine toujours dans l'un des deux états terminaux :

  • status.state == "completed" — les résultats se trouvent dans result.artifacts. Chaque artefact possède un artifactId, un name facultatif et une ou plusieurs parts (text, data ou file).
  • status.state == "failed" — la raison de l'échec se trouve dans 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": [] } }
        ]
      }
    ]
  }
}

Étape 4 : Récupérer ou annuler une tâche

Les tâches sont conservées pendant 24 heures et peuvent être récupérées par identifiant via 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 vous devez interrompre une tâche, appelez tasks/cancel avec le même identifiant. Étant donné que toutes les compétences Magisterium se résolvent de manière synchrone, l'annulation n'est utile que dans de rares scénarios de nouvelle tentative — une tâche déjà completed ou failed ne peut pas être annulée et renverra INVALID_PARAMS.

Erreurs courantes

CodeSignificationCorrection
-32004Non autoriséVérifiez l'en-tête Authorization et que le jeton d'accès est valide et n'a pas expiré.
-32005Plan payant requisMettez à niveau votre compte sur magisterium.com/plan.
-32002Compétence introuvableVérifiez que metadata.skillId correspond à un ID listé dans l'Agent Card.
-32003Limite d'utilisation dépasséePatientez retryAfter secondes (présent dans le data de l'erreur) avant de réessayer.

Consultez la Référence de l'API complète pour toutes les méthodes et codes d'erreur.