Magisterium AI

Розробники
Поділитися:

Як почати

Цей посібник проведе вас через виконання першого запиту до ендпоінта Magisterium A2A, отримання результуючого завдання та читання структурованої відповіді.

Попередні вимоги

  1. Платний план Magisterium (Pro, Organization або Enterprise). Безкоштовні облікові записи отримають від A2A помилку PLAN_REQUIRED.
  2. Токен доступу OAuth 2.0, прив'язаний до вашого облікового запису magisterium.com. A2A використовує той самий потік OAuth, що й сервер Magisterium MCP; ендпоінти авторизації, токенів і динамічної реєстрації клієнта можна знайти в метаданих OAuth за адресою https://www.magisterium.com/.well-known/oauth-authorization-server.
  3. Навички, які ви хочете викликати — див. Навички для повного списку.

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

Експортуйте ваш токен доступу як змінну середовища, щоб приклади нижче автоматично його підхоплювали:

bash
export MAGISTERIUM_TOKEN=<your-access-token-here>

Крок 1: Виявлення агента

Перед викликом ендпоінта ви можете отримати публічну Agent Card, щоб дізнатися, які навички доступні, та підтвердити версію протоколу:

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

Картка не потребує автентифікації. Оркестратори можуть кешувати її на годину — ендпоінт встановлює Cache-Control: public, max-age=3600.

Крок 2: Надішліть перше повідомлення

Усі операції A2A проходять через єдиний JSON-RPC ендпоінт: POST https://www.magisterium.com/api/v1/a2a. Приклад нижче викликає message/send для навички catholic_qa.

bash
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" }
        }
      }
    }'
typescript
const accessToken = process.env.MAGISTERIUM_TOKEN!;

const response = await fetch("https://www.magisterium.com/api/v1/a2a", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "message/send",
    params: {
      message: {
        role: "user",
        messageId: crypto.randomUUID(),
        kind: "message",
        parts: [
          { kind: "text", text: "What does the Church teach about the Real Presence?" },
        ],
        metadata: { skillId: "catholic_qa" },
      },
    },
  }),
});

const { result: task } = await response.json();
console.log(task.id, task.status.state);
for (const artifact of task.artifacts ?? []) {
  for (const part of artifact.parts) {
    if (part.kind === "text") console.log(part.text);
  }
}
python
import os
import uuid
import httpx

access_token = os.environ["MAGISTERIUM_TOKEN"]

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
        "message": {
            "role": "user",
            "messageId": str(uuid.uuid4()),
            "kind": "message",
            "parts": [
                {"kind": "text", "text": "What does the Church teach about the Real Presence?"}
            ],
            "metadata": {"skillId": "catholic_qa"},
        }
    },
}

response = httpx.post(
    "https://www.magisterium.com/api/v1/a2a",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
task = response.json()["result"]
print(task["id"], task["status"]["state"])
for artifact in task.get("artifacts", []):
    for part in artifact["parts"]:
        if part["kind"] == "text":
            print(part["text"])

Крок 3: Прочитайте відповідь

message/send повертає об'єкт Task з kind: "task". Синхронний виклик навички завжди завершується в одному з двох термінальних станів:

  • status.state == "completed" — результати знаходяться в result.artifacts. Кожен артефакт має artifactId, необов'язкове name та одну або декілька parts (text, data або file).
  • status.state == "failed" — причина збою знаходиться в status.message.parts[0].text.
json
{
  "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": [] } }
        ]
      }
    ]
  }
}

Крок 4: Отримання або скасування завдання

Завдання зберігаються 24 години і можуть бути повторно отримані за ID за допомогою tasks/get:

bash
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": 2,
      "method": "tasks/get",
      "params": { "id": "task_abc123" }
    }'

Якщо потрібно перервати завдання, викличте tasks/cancel з тим самим ID. Оскільки всі навички Magisterium виконуються синхронно, скасування корисне лише в рідкісних сценаріях повторних спроб — завдання, яке вже completed або failed, не може бути скасоване і поверне INVALID_PARAMS.

Поширені помилки

КодЗначенняВиправлення
-32004Не авторизованоПеревірте заголовок Authorization та переконайтеся, що токен доступу дійсний і не прострочений.
-32005Потрібен платний планОновіть свій обліковий запис на magisterium.com/plan.
-32002Навичку не знайденоПереконайтеся, що metadata.skillId відповідає ID зі списку в Agent Card.
-32003Перевищено ліміт запитівЗачекайте retryAfter секунд (присутнє в data помилки) перед повторною спробою.

Див. повний Довідник API для всіх методів та кодів помилок.