Magisterium AI expose les compétences suivantes via le protocole A2A. Précisez la compétence à utiliser avec metadata.skillId dans le message. Si skillId est omis, catholic_qa est utilisée par défaut.

Toutes les compétences sont invoquées via la méthode JSON-RPC message/send.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "unique-id",
      "kind": "message",
      "parts": [{ "kind": "text", "text": "your query here" }],
      "metadata": { "skillId": "document_search" }
    }
  }
}

Les réponses sont toujours renvoyées sous forme de Task (kind: "task") avec status.state: "completed" et un ou plusieurs artifacts. Chaque artefact possède un artifactId unique, un name spécifique à la compétence et une ou plusieurs parts (text, data ou file).

catholic_qa

Posez une question en langage naturel et recevez une réponse détaillée avec citations. Il s'agit de la compétence la plus puissante (et la plus gourmande en ressources) — elle fonctionne avec le même modèle que celui qui alimente magisterium.com.

Entrée : une unique partie de texte contenant la question.

Artefact : name: "catholic_qa_response" contenant :

• Une partie text avec la réponse complète.
• Une partie data avec citations (lorsque des sources ont été utilisées).
• Une partie data avec related_questions (lorsque le modèle renvoie des suggestions).

{
  "artifactId": "art_...",
  "name": "catholic_qa_response",
  "parts": [
    { "kind": "text", "text": "The Catholic Church teaches..." },
    { "kind": "data", "data": { "citations": [ /* ... */ ] } },
    { "kind": "data", "data": { "related_questions": [ /* ... */ ] } }
  ]
}

catholic_qa utilise une variante de limite d'utilisation plus stricte que les autres compétences. Consultez Référence de l'API → Limites d'utilisation.

document_search

Récupérez des références de documents qui correspondent à une requête sémantique dans la base de connaissances Magisterium.

Entrée : une unique partie de texte contenant la requête.

Artefact : name: "search_results" avec une unique partie data :

{
  "artifactId": "art_...",
  "name": "search_results",
  "parts": [
    {
      "kind": "data",
      "data": {
        "results": [
          { "id": "12345", "url": "https://...", "title": "Lumen Gentium" }
        ]
      }
    }
  ]
}

Utilisez le champ id d'un résultat pour appeler document_fetch et obtenir le texte intégral.

document_fetch

Récupérez le texte intégral et les métadonnées d'un document par son ID. Cette compétence accepte une partie data à la place d'une partie de texte :

{
  "parts": [{ "kind": "data", "data": { "id": "12345" } }]
}

Si l'appelant envoie une partie de texte, le gestionnaire la traite comme l'ID du document.

Artefact : name: "document" avec deux parties :

• Une partie text contenant le corps du document.
• Une partie data avec { id, title, author, ref }.

Si le document est introuvable, l'artefact contient une unique partie text indiquant "Document not found.".

liturgical_readings

Obtenez les lectures de la messe catholique pour une date donnée. Accepte une requête de date en langage naturel — par exemple "today", "next Sunday" ou "Easter Sunday 2026".

Entrée : une unique partie de texte contenant la requête de date.

Artefact : name: "mass_readings" avec une unique partie text contenant les lectures formatées. Si aucune lecture n'est disponible pour la date demandée, la partie contient "No mass readings found.".

saints_of_the_day

Recherchez les saints commémorés à une date donnée selon le Martyrologe romain.

Entrée : une partie data avec une date absolue, ou une partie de texte traitée comme une requête de date :

{
  "parts": [{ "kind": "data", "data": { "date": "2026-03-19" } }]
}

Artefact : name: "martyrology" avec une unique partie text contenant l'entrée du martyrologe formatée. Les dates sans données renvoient "No martyrology data found.".

Les cinq compétences ci-dessous sont des recherches dans l'annuaire. Chacune accepte une query en langage naturel (sous forme de partie de texte ou de champ data.query) plus un ID canonique optionnel, et renvoie un profil structuré dans une unique partie data. Si ni query ni un ID canonique ne sont fournis, la requête est rejetée avec INVALID_PARAMS (-32602).

Lorsque la requête ne peut être résolue, l'artefact contient une partie data de la forme { "error": "not_found", "query": "...", "hint"?: "..." } au lieu d'un profil. La tâche elle-même se termine avec succès — not_found est un résultat de recherche normal, et non une erreur de protocole.

saint_lookup

Recherchez un saint, bienheureux, vénérable ou serviteur de Dieu dans l'annuaire cd_saints (~12 500 figures).

Entrée : data.query (par ex. "Therese of Lisieux") ou data.saint_id (clé primaire canonique, par ex. "jerome"). Une simple partie de texte est acceptée comme query.

{
  "parts": [{ "kind": "data", "data": { "query": "Catherine of Siena" } }]
}

Artefact : name: "saint_profile" avec une unique partie data contenant le profil canonique — saint_id, primary_name, canonical_status, vocation, image_url, learn_more_url, vie et mort, jour de fête, cause de canonisation, patronage, iconographie, biographie, et (si plusieurs candidats ont été trouvés) un tableau alternates.

person_lookup

Recherchez une figure du clergé catholique (évêque, cardinal, archevêque, etc.) dans les annuaires cd_persons (vivants, ~3 500) et cd_persons_historical (~2 200). Les papes sont exposés via la compétence séparée pope_lookup.

Entrée : data.query (par ex. "Cardinal Tagle") ou data.person_id (clé primaire canonique). Une simple partie de texte est acceptée comme query.

{
  "parts": [{ "kind": "data", "data": { "query": "Cardinal Tagle" } }]
}

Artefact : name: "person_profile" avec une unique partie data contenant le profil canonique — person_id, source_table, primary_name, current_position, image_url, coat_of_arms_url, dates d'ordination et de consécration, élévation au cardinalat, lignée épiscopale, formation, devise, et tout alternates.

Si la requête ne se résout qu'à un pape, la réponse est { "error": "not_found", "hint": "Top match looks like a pope; try get_pope." }.

pope_lookup

Recherchez un pape dans l'annuaire cd_popes (267 figures).

Entrée : data.query (par ex. "Pope Francis", "John Paul II") ou data.pope_id (clé primaire canonique, par ex. "benedict-xvi"). Une simple partie de texte est acceptée comme query.

{
  "parts": [{ "kind": "data", "data": { "query": "John Paul II" } }]
}

Artefact : name: "pope_profile" avec une unique partie data contenant le profil papal canonique — pope_id, primary_name, papal_name, ordinal, pope_title, image_url, coat_of_arms_url, birth_name, origin, pontificate, statut de béatification et de canonisation, et tout alternates.

Si la requête ne se résout qu'à un membre du clergé non-pape, la réponse est { "error": "not_found", "hint": "Top match looks like a non-pope clergy member; try get_person." }.

diocese_lookup

Recherchez une juridiction ecclésiastique (diocèse, archidiocèse, éparchie, etc.) dans l'annuaire des diocèses (~3 200 juridictions dans le monde).

Entrée : data.query (par ex. "Archdiocese of Manila") ou data.source_code (clé primaire canonique, par ex. "dmaml"). Une simple partie de texte est acceptée comme query.

{
  "parts": [{ "kind": "data", "data": { "query": "Archdiocese of Manila" } }]
}

Artefact : name: "diocese_profile" avec une unique partie data contenant les métadonnées de l'annuaire (source_code, primary_name, jurisdiction_type, rite, country, region_primary, state, city, metropolitan, depends_on, province, cathedral, patron_saint, area, erected, elevated, official_website, image_url, current_bishop) ainsi que :

• recent_statistics — jusqu'à 5 années de chiffres clés (catholiques, population totale, pourcentage de catholiques, total de prêtres, paroisses, baptêmes, séminaristes).
• latest_financials — les principales mesures du dernier exercice fiscal (revenus totaux, dépenses totales, actifs nets, actifs totaux, excédent/déficit) lorsqu'elles sont disponibles, avec la devise.
• alternates — lorsque plusieurs candidats correspondent.

Pour une analyse de tendances pluriannuelle, utilisez plutôt diocese_statistics_lookup.

diocese_statistics_lookup

Renvoie la série temporelle annuelle complète des statistiques d'un diocèse — l'ensemble des 19 mesures suivies dans diocese_statistics.

Entrée : data.query ou data.source_code (l'une est obligatoire), plus des bornes inclusives optionnelles :

{
  "parts": [{
    "kind": "data",
    "data": {
      "source_code": "dmaml",
      "start_year": 2010,
      "end_year": 2024
    }
  }]
}

Artefact : name: "diocese_statistics_time_series" avec une unique partie data contenant source_code, diocese_name, year_range: { start, end }, et un tableau rows. Chaque ligne porte 19 mesures pour une année : catholics, total_population, percent_catholic, diocesan_priests, religious_priests, total_priests, catholics_per_priest, permanent_deacons, male_religious, female_religious, parishes, area_km2, churches_or_stations, diocesan_priests_ordained, religious_priests_ordained, seminarians, educational_institutes, charitable_institutes, baptisms.