Magisterium AI

Nhà phát triển
Chia sẻ:

Bắt đầu

Hướng dẫn này sẽ dẫn bạn qua các bước để gửi yêu cầu đầu tiên đến điểm cuối A2A của Magisterium, truy xuất nhiệm vụ kết quả và đọc phản hồi có cấu trúc.

Yêu cầu tiên quyết

  1. Một gói Magisterium trả phí (Pro, Tổ chức hoặc Doanh nghiệp). Các tài khoản miễn phí sẽ nhận lỗi PLAN_REQUIRED từ A2A.
  2. Một access token OAuth 2.0 gắn với tài khoản magisterium.com của bạn. A2A dùng cùng luồng OAuth như máy chủ Magisterium MCP; hãy lấy các điểm cuối ủy quyền, token và đăng ký động từ metadata OAuth tại https://www.magisterium.com/.well-known/oauth-authorization-server.
  3. Các kỹ năng bạn muốn gọi — xem Kỹ năng để biết danh sách đầy đủ.

Lưu ý: Các khóa API lâu dài được tạo trong API Console hoạt động với Chat Completions, Search và News, nhưng không hợp lệ với A2A — A2A chỉ chấp nhận token người dùng do OAuth cấp.

Xuất access token của bạn dưới dạng biến môi trường để các ví dụ bên dưới tự động nhận được:

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

Bước 1: Khám phá Agent

Trước khi gọi điểm cuối, bạn có thể tải Agent Card công khai để xem những kỹ năng nào khả dụng và xác nhận phiên bản giao thức:

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

Card này không yêu cầu xác thực. Các bộ điều phối có thể cache nó trong một giờ — điểm cuối đặt Cache-Control: public, max-age=3600.

Bước 2: Gửi tin nhắn đầu tiên

Tất cả các thao tác A2A đều đi qua một điểm cuối JSON-RPC duy nhất: POST https://www.magisterium.com/api/v1/a2a. Ví dụ bên dưới gọi message/send trên kỹ năng 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"])

Bước 3: Đọc phản hồi

message/send trả về một đối tượng Task có kind: "task". Một lời gọi kỹ năng đồng bộ luôn kết thúc ở một trong hai trạng thái cuối:

  • status.state == "completed" — kết quả nằm trong result.artifacts. Mỗi artifact có một artifactId, một name tùy chọn và một hoặc nhiều parts (text, data hoặc file).
  • status.state == "failed" — lý do thất bại nằm ở 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": [] } }
        ]
      }
    ]
  }
}

Bước 4: Lấy lại hoặc Hủy một Nhiệm vụ

Các nhiệm vụ được lưu trong 24 giờ và có thể được tải lại theo ID bằng 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" }
    }'

Nếu bạn cần hủy bỏ một nhiệm vụ, hãy gọi tasks/cancel với cùng một ID. Vì tất cả các kỹ năng của Magisterium đều giải quyết đồng bộ, việc hủy chỉ hữu ích trong các kịch bản thử lại hiếm — một nhiệm vụ đã ở trạng thái completed hoặc failed không thể bị hủy và sẽ trả về INVALID_PARAMS.

Các lỗi thường gặp

MãÝ nghĩaCách khắc phục
-32004Không được phépKiểm tra header Authorization và đảm bảo access token hợp lệ và chưa hết hạn.
-32005Yêu cầu gói trả phíNâng cấp tài khoản của bạn tại magisterium.com/plan.
-32002Không tìm thấy kỹ năngXác minh metadata.skillId khớp với một ID được liệt kê trong Agent Card.
-32003Vượt quá giới hạn tốc độĐợi retryAfter giây (có trong data của lỗi) trước khi thử lại.

Xem toàn bộ Tham khảo API để biết mọi phương thức và mã lỗi.