Magisterium AI cung cấp các kỹ năng sau thông qua giao thức A2A. Chỉ định kỹ năng sẽ dùng qua metadata.skillId trong tin nhắn. Nếu skillId bị bỏ qua, catholic_qa sẽ được dùng làm mặc định.

Tất cả kỹ năng đều được gọi qua phương thức 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" }
    }
  }
}

Phản hồi luôn quay về dưới dạng Task (kind: "task") với status.state: "completed" và một hoặc nhiều artifacts. Mỗi artifact có một artifactId duy nhất, một name đặc trưng cho kỹ năng và một hoặc nhiều parts (text, data hoặc file).

catholic_qa

Đặt một câu hỏi bằng ngôn ngữ tự nhiên và nhận một câu trả lời dài, có trích dẫn. Đây là kỹ năng mạnh nhất (và tiêu tốn tài nguyên nhất) — nó chạy trên cùng một mô hình đang vận hành magisterium.com.

Đầu vào: một phần text duy nhất chứa câu hỏi.

Artifact: name: "catholic_qa_response" bao gồm:

• Một phần text với câu trả lời đầy đủ.
• Một phần data với citations (khi có bất kỳ nguồn nào được sử dụng).
• Một phần data với related_questions (khi mô hình trả về các gợi ý).

{
  "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 sử dụng biến thể giới hạn tốc độ nghiêm ngặt hơn các kỹ năng khác. Xem Tham khảo API → Giới hạn tốc độ.

document_search

Truy xuất các tham chiếu tài liệu khớp với một truy vấn ngữ nghĩa trong cơ sở tri thức Magisterium.

Đầu vào: một phần text duy nhất chứa truy vấn.

Artifact: name: "search_results" với một phần data duy nhất:

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

Dùng trường id trong kết quả để gọi document_fetch lấy toàn văn.

document_fetch

Lấy toàn văn và siêu dữ liệu của một tài liệu theo ID. Kỹ năng này chấp nhận một phần data thay vì phần text:

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

Nếu người gọi gửi một phần text, trình xử lý sẽ chuyển sang coi đó là ID tài liệu.

Artifact: name: "document" với hai phần:

• Một phần text chứa nội dung tài liệu.
• Một phần data với { id, title, author, ref }.

Nếu không tìm thấy tài liệu, artifact chứa một phần text duy nhất có nội dung "Document not found.".

liturgical_readings

Lấy bài đọc Thánh Lễ Công giáo cho một ngày nhất định. Chấp nhận truy vấn ngày theo ngôn ngữ tự nhiên — ví dụ "today", "next Sunday" hoặc "Easter Sunday 2026".

Đầu vào: một phần text duy nhất với truy vấn ngày.

Artifact: name: "mass_readings" với một phần text duy nhất chứa các bài đọc đã được định dạng. Nếu không có bài đọc cho ngày được yêu cầu, nội dung của phần sẽ là "No mass readings found.".

saints_of_the_day

Tra cứu các vị thánh được tưởng nhớ trong một ngày nhất định từ Sổ Tử đạo Rôma.

Đầu vào: một phần data với một ngày tuyệt đối, hoặc một phần text được coi là truy vấn ngày:

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

Artifact: name: "martyrology" với một phần text duy nhất chứa mục tử đạo đã được định dạng. Những ngày không có dữ liệu sẽ trả về "No martyrology data found.".

Năm kỹ năng dưới đây là tra cứu thư mục. Mỗi kỹ năng nhận một query bằng ngôn ngữ tự nhiên (dưới dạng phần text hoặc trường data.query) cùng một ID chuẩn tùy chọn, và trả về một hồ sơ có cấu trúc trong một phần data duy nhất. Nếu không cung cấp cả query lẫn ID chuẩn, yêu cầu sẽ bị từ chối với INVALID_PARAMS (-32602).

Khi không thể giải quyết truy vấn, artifact chứa một phần data có dạng { "error": "not_found", "query": "...", "hint"?: "..." } thay cho hồ sơ. Tác vụ vẫn hoàn tất thành công — not_found là kết quả tra cứu thông thường, không phải lỗi giao thức.

saint_lookup

Tra cứu một vị thánh, chân phước, đáng kính hoặc tôi tớ Chúa từ thư mục cd_saints (khoảng 12.500 nhân vật).

Đầu vào: data.query (ví dụ "Therese of Lisieux") hoặc data.saint_id (khóa chính chuẩn, ví dụ "jerome"). Một phần text trần cũng được chấp nhận như query.

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

Artifact: name: "saint_profile" với một phần data duy nhất chứa hồ sơ chuẩn — saint_id, primary_name, canonical_status, vocation, image_url, learn_more_url, sinh-tử, ngày lễ, lý do phong thánh, bổn mạng, hình tượng, tiểu sử, và (nếu tìm thấy nhiều ứng viên) một mảng alternates.

person_lookup

Tra cứu một giáo sĩ Công giáo (giám mục, hồng y, tổng giám mục, v.v.) từ các thư mục cd_persons (đang sống, khoảng 3.500 vị) và cd_persons_historical (khoảng 2.200 vị). Các giáo hoàng được cung cấp qua kỹ năng riêng pope_lookup.

Đầu vào: data.query (ví dụ "Cardinal Tagle") hoặc data.person_id (khóa chính chuẩn). Một phần text trần cũng được chấp nhận như query.

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

Artifact: name: "person_profile" với một phần data duy nhất chứa hồ sơ chuẩn — person_id, source_table, primary_name, current_position, image_url, coat_of_arms_url, ngày thụ phong linh mục và tấn phong giám mục, ngày được nâng lên hồng y, tông truyền giám mục, học vấn, khẩu hiệu, và bất kỳ alternates nào.

Nếu truy vấn chỉ giải quyết được tới một giáo hoàng, phản hồi là { "error": "not_found", "hint": "Top match looks like a pope; try get_pope." }.

pope_lookup

Tra cứu một giáo hoàng từ thư mục cd_popes (267 vị).

Đầu vào: data.query (ví dụ "Pope Francis", "John Paul II") hoặc data.pope_id (khóa chính chuẩn, ví dụ "benedict-xvi"). Một phần text trần cũng được chấp nhận như query.

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

Artifact: name: "pope_profile" với một phần data duy nhất chứa hồ sơ giáo hoàng chuẩn — pope_id, primary_name, papal_name, ordinal, pope_title, image_url, coat_of_arms_url, birth_name, origin, pontificate, tình trạng phong chân phước và phong thánh, và bất kỳ alternates nào.

Nếu truy vấn chỉ giải quyết được tới một giáo sĩ không phải giáo hoàng, phản hồi là { "error": "not_found", "hint": "Top match looks like a non-pope clergy member; try get_person." }.

diocese_lookup

Tra cứu một quyền tài phán giáo hội (giáo phận, tổng giáo phận, giáo phận Đông phương, v.v.) từ thư mục các giáo phận (khoảng 3.200 quyền tài phán trên toàn thế giới).

Đầu vào: data.query (ví dụ "Archdiocese of Manila") hoặc data.source_code (khóa chính chuẩn, ví dụ "dmaml"). Một phần text trần cũng được chấp nhận như query.

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

Artifact: name: "diocese_profile" với một phần data duy nhất chứa siêu dữ liệu thư mục (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) cùng với:

• recent_statistics — tối đa 5 năm các con số chính (số tín hữu Công giáo, tổng dân số, tỷ lệ Công giáo, tổng số linh mục, số giáo xứ, số người được rửa tội, số chủng sinh).
• latest_financials — các chỉ số chính của năm tài khóa gần nhất (tổng thu, tổng chi, tài sản ròng, tổng tài sản, thặng dư/thâm hụt) khi có sẵn, kèm đơn vị tiền tệ.
• alternates — khi có nhiều ứng viên khớp.

Để phân tích xu hướng nhiều năm, hãy dùng diocese_statistics_lookup thay thế.

diocese_statistics_lookup

Trả về toàn bộ chuỗi thời gian thống kê hằng năm của một giáo phận — toàn bộ 19 chỉ số được theo dõi trong diocese_statistics.

Đầu vào: data.query hoặc data.source_code (cần có một trong hai), cộng với các giới hạn bao đóng tùy chọn:

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

Artifact: name: "diocese_statistics_time_series" với một phần data duy nhất chứa source_code, diocese_name, year_range: { start, end }, và một mảng rows. Mỗi dòng mang 19 chỉ số cho một năm: 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.