Giúp các AI agent của bạn khám phá, giao tiếp và giao việc cho Magisterium AI bằng giao thức mở A2A (Agent-to-Agent).

Vì sao chọn A2A?

Trong khi MCP cho phép các công cụ AI truy cập tri thức của Magisterium, A2A cho phép các agent AI hợp tác với Magisterium như một thành viên ngang hàng. Một agent điều phối có thể khám phá các khả năng của Magisterium, gửi nhiệm vụ cho nó và nhận về các kết quả có cấu trúc — tất cả đều thông qua một giao diện JSON-RPC tiêu chuẩn.

Yêu cầu gói trả phí. Điểm cuối A2A chỉ có sẵn trên các gói Pro, Tổ chức và Doanh nghiệp. Tài khoản miễn phí sẽ nhận lỗi PLAN_REQUIRED (-32005). Xem Giá MCP để biết giới hạn gói hiện tại — A2A dùng chung pool giới hạn tốc độ với MCP.

Khám phá Agent

Magisterium AI công bố một Agent Card công khai tại:

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

Đây là cách các agent bên ngoài khám phá các kỹ năng khả dụng, các yêu cầu xác thực và URL điểm cuối A2A. Card này tuân theo đặc tả A2A và không yêu cầu xác thực để tải về.

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

Điểm cuối A2A

Điểm cuối JSON-RPC cho tất cả các thao tác A2A là:

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

Tất cả các yêu cầu đều dùng POST với header Content-Type: application/json và một phong bì JSON-RPC 2.0 tiêu chuẩn.

Khả năng

Agent Card công bố các khả năng sau:

Xác thực

A2A sử dụng cùng cơ chế xác thực bằng token người dùng OAuth 2.0 như máy chủ Magisterium MCP. Bạn phải có tài khoản trên magisterium.com để gọi điểm cuối A2A.

Magisterium công bố metadata OAuth 2.0 tại https://www.magisterium.com/.well-known/oauth-authorization-server, bao gồm điểm cuối ủy quyền, điểm cuối token và điểm cuối đăng ký client động. Các client triển khai luồng OAuth 2.0 Authorization Code (kèm PKCE) có thể lấy access token từ metadata này; xem tài liệu xác thực MCP để biết cấu hình phía client tiêu chuẩn.

Khi đã có access token, đính kèm nó vào header Authorization của mọi yêu cầu A2A:

Authorization: Bearer $MAGISTERIUM_TOKEN

Các khóa API lâu dài được tạo trong API Console chỉ dành cho các điểm cuối Chat Completions, Search và News — chúng sẽ không xác thực được với A2A. Hãy dùng token người dùng do OAuth cấp thay thế.

Token thiếu hoặc không hợp lệ sẽ trả về lỗi UNAUTHORIZED (-32004).

Ví dụ nhanh

Gửi một câu hỏi cho kỹ năng 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" }
        }
      }
    }'

Phản hồi là một Task đã hoàn thành với câu trả lời và trích dẫn nằm bên trong 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": [ /* ... */ ] } }
        ]
      }
    ]
  }
}

Các bước tiếp theo

• Bắt đầu — thực hiện yêu cầu A2A đầu tiên của bạn bằng curl, Python và TypeScript.
• Kỹ năng — danh sách đầy đủ các kỹ năng được cung cấp qua A2A, kèm theo cấu trúc đầu vào và đầu ra cho từng kỹ năng.
• Tham khảo API — các phương thức JSON-RPC, mã lỗi và vòng đời nhiệm vụ.