Toutes les méthodes sont appelées via POST sur https://www.magisterium.com/api/v1/a2a en utilisant JSON-RPC 2.0. Chaque requête doit inclure Authorization: Bearer $MAGISTERIUM_TOKEN (un jeton utilisateur émis via OAuth — voir Authentification) et Content-Type: application/json.

Méthodes

message/send

Envoyez un message à une compétence et recevez une tâche terminée. Toutes les compétences Magisterium sont synchrones — la réponse contient l'état terminal de la tâche (completed ou failed), jamais un état intermédiaire working.

Paramètres :

Champ	Type	Requis	Description
message	Message	Oui	Le message de l'utilisateur, avec ses parties et éventuellement des métadonnées.
message.role	string	Oui	Doit être "user".
message.messageId	string	Oui	Identifiant unique pour ce message.
message.kind	string	Oui	Doit être "message".
message.parts	Part[]	Oui	Au moins une partie (text ou data).
message.metadata.skillId	string	Non	Compétence à invoquer. Par défaut : catholic_qa.
message.contextId	string	Non	ID de contexte facultatif pour regrouper les tâches associées. S'il est omis, le serveur en génère un.
configuration	object	Non	Réservé pour un usage futur.

Renvoie : un objet Task avec kind: "task".

tasks/get

Récupérez une tâche précédemment créée par son ID.

Paramètres :

Champ	Type	Requis	Description
id	string	Oui	L'ID de la tâche renvoyé par message/send.

Renvoie : l'objet Task, ou une erreur TASK_NOT_FOUND si elle a expiré ou est introuvable. Les tâches sont conservées pendant 24 heures.

tasks/cancel

Annulez une tâche si elle est dans un état annulable. Comme toutes les compétences se résolvent de manière synchrone, la plupart des tâches sont déjà dans un état terminal (completed / failed) au moment où la réponse est renvoyée — tenter d'annuler une tâche terminale renvoie INVALID_PARAMS avec un message Invalid state transition.

Paramètres :

Champ	Type	Requis	Description
id	string	Oui	L'ID de la tâche à annuler.

Renvoie : l'objet Task mis à jour avec status.state: "canceled".

Cycle de vie de la tâche

Les compétences de Magisterium s'exécutent de manière synchrone, de sorte qu'une tâche n'est persistée dans le stockage qu'une fois la compétence terminée — toujours dans un état terminal. Les états submitted et working font partie de la spécification A2A plus large mais ne sont jamais produits par l'implémentation de Magisterium ; vous n'observerez que l'un des trois états terminaux ci-dessous.

État	Signification
completed	Terminal — les résultats se trouvent dans artifacts. Renvoyé par message/send lorsque la compétence se termine avec succès.
failed	Terminal — status.message contient la raison de l'échec. Renvoyé par message/send lorsque la compétence lève une exception.
canceled	Terminal — uniquement atteignable en appelant tasks/cancel sur une tâche non terminale. Comme les tâches sont déjà terminales au moment où message/send renvoie, en pratique l'annulation est rejetée avec INVALID_PARAMS pour toute tâche dont vous disposez d'un identifiant.

Chaque tâche contient également :

• contextId — un identifiant de regroupement que vous pouvez réutiliser dans des messages de suivi pour lier des tâches apparentées.
• history — la liste ordonnée des messages de l'utilisateur et de l'agent qui ont produit les artefacts de la tâche.

Codes d'erreur

Code	Nom	Description
-32700	Parse error	Corps JSON invalide.
-32600	Invalid request	Champs jsonrpc, method ou id manquants.
-32601	Method not found	Méthode JSON-RPC inconnue.
-32602	Invalid params	Paramètres manquants ou invalides (renvoyé également pour les transitions d'état invalides de tasks/cancel).
-32603	Internal error	Erreur inattendue côté serveur.
-32001	Task not found	L'ID de la tâche n'existe pas ou a expiré.
-32002	Skill not found	skillId inconnu dans les métadonnées du message.
-32003	Rate limit exceeded	Trop de requêtes. Consultez retryAfter (secondes) dans le data de l'erreur.
-32004	Unauthorized	Jeton Bearer manquant ou invalide.
-32005	Paid plan required	A2A nécessite un plan Pro, Organisation ou Entreprise.

Le statut HTTP reflète la classe de l'erreur : 401 pour UNAUTHORIZED, 403 pour PLAN_REQUIRED, 429 pour RATE_LIMITED, et 200 pour toutes les autres erreurs JSON-RPC (selon la convention JSON-RPC consistant à renvoyer 200 avec un corps error).

Limites d'utilisation

A2A partage le même pool de limites d'utilisation que MCP — consultez la Tarification MCP pour les plafonds de requêtes par plan.

Deux variantes sont appliquées :

• Par défaut — s'applique à document_search, document_fetch, liturgical_readings et saints_of_the_day.
• Coûteuse — s'applique uniquement à catholic_qa, car elle exécute un pipeline de réponse adossé à un LLM. Cette variante utilise un plafond plus strict et plus bas.

Lorsque vous atteignez une limite, l'objet data de l'erreur contient retryAfter en secondes. Les appelants doivent patienter pendant cet intervalle avant de réessayer.

CORS

Le point de terminaison répond aux requêtes préliminaires OPTIONS et renvoie des en-têtes CORS permissifs (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), de sorte qu'A2A peut être appelé depuis des orchestrateurs en navigateur sans proxy.