Semua metode dipanggil melalui POST ke https://www.magisterium.com/api/v1/a2a menggunakan JSON-RPC 2.0. Setiap permintaan harus menyertakan Authorization: Bearer $MAGISTERIUM_TOKEN (token pengguna yang diterbitkan OAuth — lihat Autentikasi) dan Content-Type: application/json.

Metode

message/send

Kirim pesan ke sebuah keterampilan dan terima tugas yang telah selesai. Semua keterampilan Magisterium bersifat sinkron — respons berisi status tugas terminal (completed atau failed), tidak pernah status working antara.

Params:

Field	Tipe	Wajib	Deskripsi
message	Message	Ya	Pesan pengguna dengan parts dan metadata opsional.
message.role	string	Ya	Harus "user".
message.messageId	string	Ya	ID unik untuk pesan ini.
message.kind	string	Ya	Harus "message".
message.parts	Part[]	Ya	Setidaknya satu part (text atau data).
message.metadata.skillId	string	Tidak	Keterampilan yang akan dipanggil. Default-nya catholic_qa.
message.contextId	string	Tidak	Context ID opsional untuk mengelompokkan tugas terkait. Jika dihilangkan, server akan menghasilkannya.
configuration	object	Tidak	Dicadangkan untuk penggunaan mendatang.

Mengembalikan: Objek Task dengan kind: "task".

tasks/get

Mengambil tugas yang sebelumnya dibuat berdasarkan ID-nya.

Params:

Field	Tipe	Wajib	Deskripsi
id	string	Ya	ID tugas yang dikembalikan dari message/send.

Mengembalikan: Objek Task, atau error TASK_NOT_FOUND jika kedaluwarsa atau tidak ada. Tugas disimpan selama 24 jam.

tasks/cancel

Membatalkan tugas jika dalam keadaan dapat dibatalkan. Karena semua keterampilan diselesaikan secara sinkron, sebagian besar tugas sudah berada dalam status terminal (completed / failed) pada saat respons dikembalikan — mencoba membatalkan tugas terminal akan mengembalikan INVALID_PARAMS dengan pesan Invalid state transition.

Params:

Field	Tipe	Wajib	Deskripsi
id	string	Ya	ID tugas yang akan dibatalkan.

Mengembalikan: Objek Task terbaru dengan status.state: "canceled".

Siklus Hidup Tugas

Keterampilan Magisterium berjalan secara sinkron, sehingga sebuah tugas hanya disimpan ke storage setelah keterampilan selesai — selalu dalam status terminal. Status submitted dan working adalah bagian dari spesifikasi A2A yang lebih luas, tetapi tidak pernah dihasilkan oleh implementasi Magisterium; Anda hanya akan mengamati salah satu dari tiga status terminal di bawah ini.

Status	Arti
completed	Terminal — hasilnya ada di artifacts. Dikembalikan oleh message/send ketika keterampilan berhasil selesai.
failed	Terminal — status.message berisi alasan kegagalan. Dikembalikan oleh message/send ketika keterampilan melempar error.
canceled	Terminal — hanya dapat dicapai dengan memanggil tasks/cancel pada tugas yang belum terminal. Karena tugas sudah dalam status terminal pada saat message/send kembali, dalam praktiknya pembatalan ditolak dengan INVALID_PARAMS untuk setiap tugas yang handle-nya Anda pegang.

Setiap tugas juga membawa:

• contextId — pengenal pengelompokan yang dapat Anda gunakan kembali pada pesan tindak lanjut untuk mengaitkan tugas-tugas terkait.
• history — daftar berurutan pesan pengguna dan agen yang menghasilkan artifact tugas.

Kode Error

Kode	Nama	Deskripsi
-32700	Parse error	Body JSON tidak valid.
-32600	Invalid request	Field jsonrpc, method, atau id hilang.
-32601	Method not found	Metode JSON-RPC tidak dikenal.
-32602	Invalid params	Parameter hilang atau tidak valid (juga dikembalikan untuk transisi status tasks/cancel yang tidak valid).
-32603	Internal error	Kegagalan tak terduga di sisi server.
-32001	Task not found	ID tugas tidak ada atau telah kedaluwarsa.
-32002	Skill not found	skillId tidak dikenal di metadata pesan.
-32003	Rate limit exceeded	Terlalu banyak permintaan. Periksa retryAfter (detik) di data error.
-32004	Unauthorized	Token Bearer hilang atau tidak valid.
-32005	Paid plan required	A2A memerlukan paket Pro, Organisasi, atau Perusahaan.

Status HTTP mencerminkan kelas error: 401 untuk UNAUTHORIZED, 403 untuk PLAN_REQUIRED, 429 untuk RATE_LIMITED, dan 200 untuk semua error JSON-RPC lainnya (sesuai konvensi JSON-RPC yang mengembalikan 200 dengan body error).

Batas Laju

A2A berbagi pool pembatas laju yang sama dengan MCP — lihat Harga MCP untuk batas permintaan per paket.

Dua varian diberlakukan:

• Default — berlaku untuk document_search, document_fetch, liturgical_readings, dan saints_of_the_day.
• Mahal — hanya berlaku untuk catholic_qa, karena ia menjalankan pipeline jawaban berbasis LLM. Varian ini menggunakan batas yang lebih ketat dan lebih rendah.

Ketika Anda mencapai batas, objek data error berisi retryAfter dalam detik. Pemanggil harus menunda selama interval itu sebelum mencoba lagi.

CORS

Endpoint merespons permintaan preflight OPTIONS dan mengembalikan header CORS yang permisif (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), sehingga A2A dapat dipanggil dari orkestrator berbasis browser tanpa proksi.