O Magisterium AI expõe as seguintes habilidades através do protocolo A2A. Especifique a habilidade a utilizar através de metadata.skillId na mensagem. Se skillId for omitido, catholic_qa é usada por predefinição.

Todas as habilidades são invocadas através do método 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" }
    }
  }
}

As respostas são sempre devolvidas como uma Task (kind: "task") com status.state: "completed" e um ou mais artifacts. Cada artefacto tem um artifactId único, um name específico da habilidade e uma ou mais parts (text, data ou file).

catholic_qa

Coloque uma pergunta em linguagem natural e receba uma resposta extensa com citações. Esta é a habilidade mais capaz (e mais exigente em termos de recursos) — é executada no mesmo modelo que alimenta o magisterium.com.

Entrada: uma única parte de texto com a pergunta.

Artefacto: name: "catholic_qa_response" contendo:

• Uma parte text com a resposta completa.
• Uma parte data com citations (quando foram utilizadas fontes).
• Uma parte data com related_questions (quando o modelo devolve sugestões).

{
  "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 utiliza uma variante de limite de utilização mais estrita do que as restantes habilidades. Consulte Referência da API → Limites de utilização.

document_search

Obtém referências a documentos que correspondam a uma consulta semântica na base de conhecimento do Magisterium.

Entrada: uma única parte de texto com a consulta.

Artefacto: name: "search_results" com uma única parte data:

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

Use o campo id de um resultado para chamar document_fetch e obter o texto completo.

document_fetch

Obtém o texto completo e os metadados de um documento pelo seu ID. Esta habilidade aceita uma parte data em vez de uma parte de texto:

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

Se o chamador enviar uma parte de texto, o handler trata-a como o ID do documento.

Artefacto: name: "document" com duas partes:

• Uma parte text contendo o corpo do documento.
• Uma parte data com { id, title, author, ref }.

Se o documento não for encontrado, o artefacto contém uma única parte text com o texto "Document not found.".

liturgical_readings

Obtenha as leituras da Missa católica para uma dada data. Aceita uma consulta de data em linguagem natural — por exemplo, "today", "next Sunday" ou "Easter Sunday 2026".

Entrada: uma única parte de texto com a consulta de data.

Artefacto: name: "mass_readings" com uma única parte text contendo as leituras formatadas. Se não houver leituras disponíveis para a data solicitada, a parte apresentará "No mass readings found.".

saints_of_the_day

Consulte os santos comemorados numa dada data segundo o Martirológio Romano.

Entrada: uma parte data com uma data absoluta, ou uma parte de texto tratada como consulta de data:

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

Artefacto: name: "martyrology" com uma única parte text contendo a entrada do martirológio formatada. Datas sem dados devolvem "No martyrology data found.".

As cinco habilidades abaixo são pesquisas de diretório. Cada uma aceita uma query em linguagem natural (como parte de texto ou como campo data.query) mais um ID canónico opcional, e devolve um perfil estruturado dentro de uma única parte data. Se nem query nem um ID canónico forem fornecidos, o pedido é rejeitado com INVALID_PARAMS (-32602).

Quando a consulta não pode ser resolvida, o artefacto contém uma parte data com o formato { "error": "not_found", "query": "...", "hint"?: "..." } em vez de um perfil. A própria tarefa é concluída com sucesso — not_found é um resultado normal de pesquisa, não um erro de protocolo.

saint_lookup

Pesquise um santo, beato, venerável ou servo de Deus no diretório cd_saints (~12.500 figuras).

Entrada: data.query (por exemplo, "Therese of Lisieux") ou data.saint_id (chave primária canónica, por exemplo, "jerome"). Uma parte de texto isolada é aceite como query.

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

Artefacto: name: "saint_profile" com uma única parte data contendo o perfil canónico — saint_id, primary_name, canonical_status, vocation, image_url, learn_more_url, vida e morte, dia de festa, causa de canonização, padroado, iconografia, biografia e (se forem encontrados vários candidatos) um array alternates.

person_lookup

Pesquise uma figura do clero católico (bispo, cardeal, arcebispo, etc.) nos diretórios cd_persons (vivos, ~3.500) e cd_persons_historical (~2.200). Os papas são expostos através da habilidade separada pope_lookup.

Entrada: data.query (por exemplo, "Cardinal Tagle") ou data.person_id (chave primária canónica). Uma parte de texto isolada é aceite como query.

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

Artefacto: name: "person_profile" com uma única parte data contendo o perfil canónico — person_id, source_table, primary_name, current_position, image_url, coat_of_arms_url, datas de ordenação e consagração, elevação ao cardinalato, linhagem episcopal, formação, lema e quaisquer alternates.

Se a consulta se resolver apenas para um papa, a resposta é { "error": "not_found", "hint": "Top match looks like a pope; try get_pope." }.

pope_lookup

Pesquise um papa no diretório cd_popes (267 figuras).

Entrada: data.query (por exemplo, "Pope Francis", "John Paul II") ou data.pope_id (chave primária canónica, por exemplo, "benedict-xvi"). Uma parte de texto isolada é aceite como query.

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

Artefacto: name: "pope_profile" com uma única parte data contendo o perfil papal canónico — pope_id, primary_name, papal_name, ordinal, pope_title, image_url, coat_of_arms_url, birth_name, origin, pontificate, estado de beatificação e canonização, e quaisquer alternates.

Se a consulta se resolver apenas para um membro do clero que não seja papa, a resposta é { "error": "not_found", "hint": "Top match looks like a non-pope clergy member; try get_person." }.

diocese_lookup

Pesquise uma jurisdição eclesiástica (diocese, arquidiocese, eparquia, etc.) no diretório de dioceses (~3.200 jurisdições em todo o mundo).

Entrada: data.query (por exemplo, "Archdiocese of Manila") ou data.source_code (chave primária canónica, por exemplo, "dmaml"). Uma parte de texto isolada é aceite como query.

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

Artefacto: name: "diocese_profile" com uma única parte data contendo metadados do diretório (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) bem como:

• recent_statistics — até 5 anos de números principais (católicos, população total, percentagem de católicos, total de sacerdotes, paróquias, batismos, seminaristas).
• latest_financials — as métricas principais do exercício fiscal mais recente (receita total, despesas totais, ativos líquidos, ativos totais, superavit/défice) quando disponíveis, com a moeda.
• alternates — quando vários candidatos correspondem.

Para análise de tendências plurianuais, utilize diocese_statistics_lookup em vez disso.

diocese_statistics_lookup

Devolve a série temporal anual completa de estatísticas de uma diocese — todas as 19 métricas registadas em diocese_statistics.

Entrada: data.query ou data.source_code (um deles é obrigatório), mais limites inclusivos opcionais:

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

Artefacto: name: "diocese_statistics_time_series" com uma única parte data contendo source_code, diocese_name, year_range: { start, end } e um array rows. Cada linha apresenta 19 métricas para um ano: 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.