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.".