Magisterium AI espone le seguenti competenze tramite il protocollo A2A. Specifica la competenza da utilizzare tramite metadata.skillId nel messaggio. Se skillId viene omesso, viene utilizzata catholic_qa come predefinita.

Tutte le competenze vengono invocate tramite il metodo 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" }
    }
  }
}

Le risposte vengono sempre restituite come Task (kind: "task") con status.state: "completed" e uno o più artifacts. Ogni artefatto ha un artifactId univoco, un name specifico della competenza e una o più parts (text, data o file).

catholic_qa

Poni una domanda in linguaggio naturale e ricevi una risposta dettagliata con citazioni. È la competenza più capace (e più impegnativa in termini di risorse) — utilizza lo stesso modello che alimenta magisterium.com.

Input: una singola parte di testo con la domanda.

Artefatto: name: "catholic_qa_response" contenente:

• Una parte text con la risposta completa.
• Una parte data con citations (quando vengono utilizzate fonti).
• Una parte data con related_questions (quando il modello restituisce suggerimenti).

{
  "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 utilizza una variante dei limiti di utilizzo più rigorosa rispetto alle altre competenze. Consulta Riferimento API → Limiti di utilizzo.

document_search

Recupera riferimenti a documenti che corrispondono a una query semantica sulla base di conoscenza di Magisterium.

Input: una singola parte di testo con la query.

Artefatto: name: "search_results" con una singola parte data:

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

Utilizza il campo id di un risultato per chiamare document_fetch e ottenere il testo completo.

document_fetch

Recupera il testo completo e i metadati di un documento tramite il suo ID. Questa competenza accetta una parte data invece di una parte di testo:

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

Se il chiamante invia una parte di testo, l'handler la tratta come se fosse l'ID del documento.

Artefatto: name: "document" con due parti:

• Una parte text contenente il corpo del documento.
• Una parte data con { id, title, author, ref }.

Se il documento non viene trovato, l'artefatto contiene un'unica parte text che riporta "Document not found.".

liturgical_readings

Ottieni le letture della Messa cattolica per una data specifica. Accetta una query di data in linguaggio naturale — ad es. "today", "next Sunday" o "Easter Sunday 2026".

Input: una singola parte di testo con la query di data.

Artefatto: name: "mass_readings" con un'unica parte text contenente le letture formattate. Se non sono disponibili letture per la data richiesta, la parte riporta "No mass readings found.".

saints_of_the_day

Consulta i santi commemorati in una data specifica secondo il Martirologio Romano.

Input: una parte data con una data assoluta, oppure una parte di testo trattata come query di data:

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

Artefatto: name: "martyrology" con un'unica parte text contenente la voce del martirologio formattata. Le date senza dati restituiscono "No martyrology data found.".

Le cinque competenze seguenti sono ricerche nella directory. Ognuna accetta una query in linguaggio naturale (come parte di testo o come campo data.query) più un ID canonico opzionale, e restituisce un profilo strutturato all'interno di un'unica parte data. Se non vengono forniti né query né un ID canonico, la richiesta viene rifiutata con INVALID_PARAMS (-32602).

Quando la query non può essere risolta, l'artefatto contiene una parte data nella forma { "error": "not_found", "query": "...", "hint"?: "..." } invece di un profilo. L'attività stessa si completa comunque con successo — not_found è un risultato di ricerca normale, non un errore di protocollo.

saint_lookup

Cerca un santo, beato, venerabile o servo di Dio nella directory cd_saints (~12.500 figure).

Input: data.query (ad es. "Therese of Lisieux") o data.saint_id (chiave primaria canonica, ad es. "jerome"). Una semplice parte di testo viene accettata come query.

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

Artefatto: name: "saint_profile" con un'unica parte data contenente il profilo canonico — saint_id, primary_name, canonical_status, vocation, image_url, learn_more_url, vita e morte, giorno della festa, causa di canonizzazione, patronato, iconografia, biografia e (se sono stati trovati più candidati) un array alternates.

person_lookup

Cerca una figura del clero cattolico (vescovo, cardinale, arcivescovo, ecc.) nelle directory cd_persons (viventi, ~3.500) e cd_persons_historical (~2.200). I papi sono esposti tramite la competenza separata pope_lookup.

Input: data.query (ad es. "Cardinal Tagle") o data.person_id (chiave primaria canonica). Una semplice parte di testo viene accettata come query.

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

Artefatto: name: "person_profile" con un'unica parte data contenente il profilo canonico — person_id, source_table, primary_name, current_position, image_url, coat_of_arms_url, date di ordinazione e consacrazione, elevazione al cardinalato, lignaggio episcopale, formazione, motto e qualsiasi alternates.

Se la query si risolve solo a un papa, la risposta è { "error": "not_found", "hint": "Top match looks like a pope; try get_pope." }.

pope_lookup

Cerca un papa nella directory cd_popes (267 figure).

Input: data.query (ad es. "Pope Francis", "John Paul II") o data.pope_id (chiave primaria canonica, ad es. "benedict-xvi"). Una semplice parte di testo viene accettata come query.

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

Artefatto: name: "pope_profile" con un'unica parte data contenente il profilo papale canonico — pope_id, primary_name, papal_name, ordinal, pope_title, image_url, coat_of_arms_url, birth_name, origin, pontificate, stato di beatificazione e canonizzazione, e qualsiasi alternates.

Se la query si risolve solo a un membro del clero non papa, la risposta è { "error": "not_found", "hint": "Top match looks like a non-pope clergy member; try get_person." }.

diocese_lookup

Cerca una giurisdizione ecclesiastica (diocesi, arcidiocesi, eparchia, ecc.) nella directory delle diocesi (~3.200 giurisdizioni in tutto il mondo).

Input: data.query (ad es. "Archdiocese of Manila") o data.source_code (chiave primaria canonica, ad es. "dmaml"). Una semplice parte di testo viene accettata come query.

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

Artefatto: name: "diocese_profile" con un'unica parte data contenente i metadati della directory (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) oltre a:

• recent_statistics — fino a 5 anni di cifre principali (cattolici, popolazione totale, percentuale di cattolici, totale sacerdoti, parrocchie, battesimi, seminaristi).
• latest_financials — le metriche principali dell'esercizio fiscale più recente (entrate totali, spese totali, attivo netto, attivo totale, surplus/deficit) quando disponibili, con la valuta.
• alternates — quando corrispondono più candidati.

Per un'analisi delle tendenze pluriennale, utilizza invece diocese_statistics_lookup.

diocese_statistics_lookup

Restituisce la serie temporale annuale completa delle statistiche di una diocesi — tutte le 19 metriche tracciate in diocese_statistics.

Input: data.query o data.source_code (uno dei due è obbligatorio), più limiti inclusivi opzionali:

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

Artefatto: name: "diocese_statistics_time_series" con un'unica parte data contenente source_code, diocese_name, year_range: { start, end } e un array rows. Ogni riga contiene 19 metriche per un anno: 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.