Tham khảo API
Tất cả các phương thức đều được gọi bằng POST tới https://www.magisterium.com/api/v1/a2a sử dụng JSON-RPC 2.0. Mọi yêu cầu đều phải bao gồm Authorization: Bearer $MAGISTERIUM_TOKEN (một token người dùng do OAuth cấp — xem Xác thực) và Content-Type: application/json.
Phương thức
message/send
Gửi một tin nhắn đến một kỹ năng và nhận một nhiệm vụ đã hoàn tất. Tất cả các kỹ năng của Magisterium đều đồng bộ — phản hồi chứa trạng thái nhiệm vụ cuối cùng (completed hoặc failed), không bao giờ là trạng thái trung gian working.
Tham số:
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
message | Message | Có | Tin nhắn của người dùng với các phần và siêu dữ liệu tùy chọn. |
message.role | string | Có | Phải là "user". |
message.messageId | string | Có | ID duy nhất cho tin nhắn này. |
message.kind | string | Có | Phải là "message". |
message.parts | Part[] | Có | Ít nhất một phần (text hoặc data). |
message.metadata.skillId | string | Không | Kỹ năng để gọi. Mặc định là catholic_qa. |
message.contextId | string | Không | Context ID tùy chọn để nhóm các nhiệm vụ liên quan. Nếu bị bỏ, máy chủ sẽ tạo một. |
configuration | object | Không | Được giữ cho mục đích trong tương lai. |
Trả về: Một đối tượng Task với kind: "task".
tasks/get
Lấy một nhiệm vụ đã được tạo trước đó theo ID.
Tham số:
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id | string | Có | ID nhiệm vụ được trả về từ message/send. |
Trả về: Đối tượng Task, hoặc lỗi TASK_NOT_FOUND nếu đã hết hạn hoặc không tồn tại. Nhiệm vụ được lưu trong 24 giờ.
tasks/cancel
Hủy một nhiệm vụ nếu nó đang ở trạng thái có thể hủy. Vì tất cả kỹ năng đều giải quyết đồng bộ, hầu hết các nhiệm vụ đã ở trạng thái cuối (completed / failed) vào thời điểm phản hồi trở về — cố gắng hủy một nhiệm vụ ở trạng thái cuối sẽ trả về INVALID_PARAMS với thông báo Invalid state transition.
Tham số:
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id | string | Có | ID nhiệm vụ cần hủy. |
Trả về: Đối tượng Task đã cập nhật với status.state: "canceled".
Vòng đời nhiệm vụ
Các kỹ năng của Magisterium chạy đồng bộ, nên một nhiệm vụ chỉ được lưu vào kho sau khi kỹ năng kết thúc — luôn ở trạng thái cuối. Các trạng thái submitted và working là một phần của đặc tả A2A rộng hơn nhưng không bao giờ được tạo ra bởi cách triển khai của Magisterium; bạn sẽ chỉ quan sát thấy một trong ba trạng thái cuối dưới đây.
| Trạng thái | Ý nghĩa |
|---|---|
completed | Trạng thái cuối — kết quả nằm trong artifacts. Được trả về bởi message/send khi kỹ năng hoàn tất thành công. |
failed | Trạng thái cuối — status.message chứa lý do thất bại. Được trả về bởi message/send khi kỹ năng ném lỗi. |
canceled | Trạng thái cuối — chỉ có thể đạt được bằng cách gọi tasks/cancel trên một nhiệm vụ chưa ở trạng thái cuối. Vì các nhiệm vụ đã ở trạng thái cuối vào lúc message/send trả về, trên thực tế việc hủy bị từ chối với INVALID_PARAMS đối với bất kỳ nhiệm vụ nào bạn đang nắm giữ. |
Mỗi nhiệm vụ cũng mang theo:
contextId— một định danh nhóm mà bạn có thể tái sử dụng ở các tin nhắn theo sau để liên kết các nhiệm vụ liên quan.history— danh sách có thứ tự các tin nhắn của người dùng và agent đã tạo ra các artifact của nhiệm vụ.
Mã lỗi
| Mã | Tên | Mô tả |
|---|---|---|
-32700 | Parse error | Thân JSON không hợp lệ. |
-32600 | Invalid request | Thiếu các trường jsonrpc, method hoặc id. |
-32601 | Method not found | Phương thức JSON-RPC không xác định. |
-32602 | Invalid params | Thiếu hoặc không hợp lệ các tham số (cũng được trả về cho chuyển trạng thái tasks/cancel không hợp lệ). |
-32603 | Internal error | Lỗi phía máy chủ không mong đợi. |
-32001 | Task not found | ID nhiệm vụ không tồn tại hoặc đã hết hạn. |
-32002 | Skill not found | skillId không xác định trong siêu dữ liệu tin nhắn. |
-32003 | Rate limit exceeded | Quá nhiều yêu cầu. Kiểm tra retryAfter (giây) trong data của lỗi. |
-32004 | Unauthorized | Thiếu hoặc không hợp lệ token Bearer. |
-32005 | Paid plan required | A2A yêu cầu gói Pro, Tổ chức hoặc Doanh nghiệp. |
Trạng thái HTTP phản ánh lớp lỗi: 401 cho UNAUTHORIZED, 403 cho PLAN_REQUIRED, 429 cho RATE_LIMITED, và 200 cho tất cả các lỗi JSON-RPC khác (theo quy ước của JSON-RPC là trả 200 với một thân error).
Giới hạn tốc độ
A2A dùng chung pool giới hạn tốc độ với MCP — xem Giá MCP để biết mức trần yêu cầu theo từng gói.
Hai biến thể được áp dụng:
- Mặc định — áp dụng cho
document_search,document_fetch,liturgical_readingsvàsaints_of_the_day. - Tốn kém — chỉ áp dụng cho
catholic_qa, vì nó chạy một pipeline trả lời dựa trên LLM. Biến thể này dùng mức trần nghiêm ngặt và thấp hơn.
Khi bạn chạm giới hạn, đối tượng data của lỗi chứa retryAfter tính theo giây. Người gọi nên chờ đợi trong khoảng đó trước khi thử lại.
CORS
Điểm cuối phản hồi các yêu cầu preflight OPTIONS và trả về các header CORS thông thoáng (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), do đó A2A có thể được gọi từ các bộ điều phối trên trình duyệt mà không cần proxy.