Дайте змогу своїм ШІ-агентам виявляти Magisterium AI, спілкуватися з ним і делегувати йому завдання, використовуючи відкритий протокол A2A (Agent-to-Agent).

Навіщо A2A?

У той час як MCP дозволяє ШІ-інструментам отримувати доступ до знань Magisterium, A2A дозволяє ШІ-агентам взаємодіяти з Magisterium як з рівноправним партнером. Оркеструючий агент може виявити можливості Magisterium, надсилати йому завдання та отримувати структуровані результати — усе це через стандартний інтерфейс JSON-RPC.

Потрібен платний план. Ендпоінт A2A доступний у планах Pro, Organization та Enterprise. Безкоштовні облікові записи отримують помилку PLAN_REQUIRED (-32005). Див. Ціни MCP для актуальних лімітів планів — A2A використовує той самий пул лімітів запитів.

Виявлення агента

Magisterium AI публікує публічну Agent Card за адресою:

https://www.magisterium.com/.well-known/agent.json

Саме так зовнішні агенти виявляють доступні навички, вимоги до автентифікації та URL ендпоінта A2A. Картка відповідає специфікації A2A і не потребує автентифікації для отримання.

curl https://www.magisterium.com/.well-known/agent.json

Ендпоінт A2A

JSON-RPC ендпоінт для всіх операцій A2A:

https://www.magisterium.com/api/v1/a2a

Усі запити використовують POST із заголовком Content-Type: application/json та стандартним конвертом JSON-RPC 2.0.

Можливості

Agent Card оголошує такі можливості:

Автентифікація

A2A використовує ту саму автентифікацію OAuth 2.0 з користувацьким токеном, що й сервер Magisterium MCP. Щоб викликати ендпоінт A2A, ви повинні мати обліковий запис на magisterium.com.

Magisterium публікує метадані OAuth 2.0 за адресою https://www.magisterium.com/.well-known/oauth-authorization-server, включно з ендпоінтом авторизації, ендпоінтом токенів та ендпоінтом динамічної реєстрації клієнта. Клієнти, які реалізують потік OAuth 2.0 Authorization Code (з PKCE), можуть отримати токен доступу з цих метаданих; стандартне клієнтське налаштування див. у документації з автентифікації MCP.

Отримавши токен доступу, включайте його в заголовок Authorization кожного запиту A2A:

Authorization: Bearer $MAGISTERIUM_TOKEN

Довгоживучі API-ключі, створювані в API Console, призначені лише для ендпоінтів Chat Completions, Search і News — вони не автентифікуватимуть A2A. Використовуйте замість них користувацький токен, виданий через OAuth.

Відсутні або недійсні токени повертають помилку UNAUTHORIZED (-32004).

Швидкий приклад

Надішліть запитання до навички catholic_qa:

curl -X POST https://www.magisterium.com/api/v1/a2a \
    -H "Authorization: Bearer $MAGISTERIUM_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "message/send",
      "params": {
        "message": {
          "role": "user",
          "messageId": "msg-001",
          "kind": "message",
          "parts": [{ "kind": "text", "text": "What does the Church teach about the Real Presence?" }],
          "metadata": { "skillId": "catholic_qa" }
        }
      }
    }'

Відповідь є завершеним Task з відповіддю та цитатами всередині result.artifacts:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task_abc123",
    "contextId": "ctx_def456",
    "kind": "task",
    "status": { "state": "completed", "timestamp": "2026-04-20T12:00:00.000Z" },
    "artifacts": [
      {
        "artifactId": "art_ghi789",
        "name": "catholic_qa_response",
        "parts": [
          { "kind": "text", "text": "The Catholic Church teaches..." },
          { "kind": "data", "data": { "citations": [ /* ... */ ] } }
        ]
      }
    ]
  }
}

Наступні кроки

• Як почати — пройдіться своїм першим запитом A2A за допомогою curl, Python та TypeScript.
• Навички — повний список навичок, доступних через A2A, з форматами вхідних і вихідних даних для кожної навички.
• Довідник API — методи JSON-RPC, коди помилок і життєвий цикл завдання.