API 참조
모든 메서드는 JSON-RPC 2.0을 사용하여 https://www.magisterium.com/api/v1/a2a에 POST로 호출됩니다. 모든 요청에는 Authorization: Bearer $MAGISTERIUM_TOKEN (OAuth로 발급된 사용자 토큰 — 인증 참조)과 Content-Type: application/json이 포함되어야 합니다.
메서드
message/send
스킬에 메시지를 보내고 완료된 작업을 받습니다. 모든 Magisterium 스킬은 동기적입니다 — 응답에는 최종 작업 상태 (completed 또는 failed)가 포함되며, 중간 working 상태는 포함되지 않습니다.
매개변수:
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
message | Message | 예 | part와 선택적 메타데이터를 가진 사용자 메시지. |
message.role | string | 예 | 반드시 "user"여야 합니다. |
message.messageId | string | 예 | 이 메시지의 고유 ID. |
message.kind | string | 예 | 반드시 "message"여야 합니다. |
message.parts | Part[] | 예 | 최소 하나의 part (텍스트 또는 데이터). |
message.metadata.skillId | string | 아니요 | 호출할 스킬. 기본값은 catholic_qa. |
message.contextId | string | 아니요 | 관련 작업을 그룹화하기 위한 선택적 context ID. 생략되면 서버가 생성합니다. |
configuration | object | 아니요 | 미래 사용을 위해 예약됨. |
반환: kind: "task"를 가진 Task 객체.
tasks/get
이전에 생성된 작업을 ID로 가져옵니다.
매개변수:
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
id | string | 예 | message/send에서 반환된 작업 ID. |
반환: Task 객체, 또는 만료되었거나 누락된 경우 TASK_NOT_FOUND 오류. 작업은 24시간 동안 저장됩니다.
tasks/cancel
취소 가능한 상태인 경우 작업을 취소합니다. 모든 스킬이 동기적으로 해결되기 때문에, 응답이 반환되는 시점에 대부분의 작업은 이미 종료 상태 (completed / failed)에 있습니다 — 종료 상태의 작업을 취소하려고 하면 Invalid state transition 메시지와 함께 INVALID_PARAMS를 반환합니다.
매개변수:
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
id | string | 예 | 취소할 작업 ID. |
반환: status.state: "canceled"가 있는 업데이트된 Task 객체.
작업 라이프사이클
Magisterium의 스킬은 동기적으로 실행되므로, 작업은 스킬이 끝난 후에만 스토리지에 저장됩니다 — 항상 종료 상태입니다. submitted와 working 상태는 더 넓은 A2A 사양의 일부이지만, Magisterium 구현에서는 절대 생성되지 않습니다. 아래 세 가지 종료 상태 중 하나만 관찰할 수 있습니다.
| 상태 | 의미 |
|---|---|
completed | 종료 — 결과는 artifacts에 있습니다. 스킬이 성공적으로 완료되면 message/send에서 반환됩니다. |
failed | 종료 — status.message에 실패 이유가 포함됩니다. 스킬이 예외를 던지면 message/send에서 반환됩니다. |
canceled | 종료 — 종료 상태가 아닌 작업에 대해 tasks/cancel을 호출해야만 도달할 수 있습니다. message/send가 반환될 때 작업은 이미 종료 상태이므로, 실제로는 핸들을 가지고 있는 모든 작업에 대한 취소는 INVALID_PARAMS로 거부됩니다. |
모든 작업은 또한 다음을 가집니다:
contextId— 관련 작업을 연결하기 위해 후속 메시지에서 재사용할 수 있는 그룹 식별자.history— 작업의 artifact를 생성한 사용자 및 에이전트 메시지의 순서가 지정된 목록.
오류 코드
| 코드 | 이름 | 설명 |
|---|---|---|
-32700 | Parse error | 유효하지 않은 JSON 본문. |
-32600 | Invalid request | jsonrpc, method 또는 id 필드 누락. |
-32601 | Method not found | 알 수 없는 JSON-RPC 메서드. |
-32602 | Invalid params | 매개변수 누락 또는 유효하지 않음 (유효하지 않은 tasks/cancel 상태 전환에서도 반환됨). |
-32603 | Internal error | 예기치 않은 서버 측 오류. |
-32001 | Task not found | 작업 ID가 존재하지 않거나 만료되었습니다. |
-32002 | Skill not found | 메시지 메타데이터의 알 수 없는 skillId. |
-32003 | Rate limit exceeded | 요청이 너무 많습니다. 오류 data에서 retryAfter (초)를 확인하세요. |
-32004 | Unauthorized | Bearer 토큰 누락 또는 유효하지 않음. |
-32005 | Paid plan required | A2A에는 Pro, Organization 또는 Enterprise 플랜이 필요합니다. |
HTTP 상태는 오류 클래스를 반영합니다: UNAUTHORIZED는 401, PLAN_REQUIRED는 403, RATE_LIMITED는 429, 기타 모든 JSON-RPC 오류는 200 (error 본문과 함께 200을 반환하는 JSON-RPC 규약에 따름).
속도 제한
A2A는 MCP와 동일한 속도 제한 풀을 공유합니다 — 플랜별 요청 상한은 MCP 가격을 참조하세요.
두 가지 변형이 적용됩니다:
- 기본 —
document_search,document_fetch,liturgical_readings,saints_of_the_day에 적용됩니다. - 비싼 것 —
catholic_qa에만 적용되며, 이는 LLM 기반 답변 파이프라인을 실행하기 때문입니다. 이 변형은 더 엄격하고 낮은 상한을 사용합니다.
제한에 도달하면 오류 data 객체에 retryAfter가 초 단위로 포함됩니다. 호출자는 재시도 전에 해당 간격만큼 백오프해야 합니다.
CORS
이 엔드포인트는 OPTIONS 프리플라이트 요청에 응답하고 허용적인 CORS 헤더 (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization)를 반환하므로, A2A는 프록시 없이 브라우저 기반 오케스트레이터에서 호출될 수 있습니다.