Magisterium AI

개발자
공유:

시작하기

이 가이드에서는 Magisterium A2A 엔드포인트에 첫 요청을 보내고, 결과 작업을 가져오고, 구조화된 응답을 읽는 과정을 안내합니다.

전제 조건

  1. 유료 Magisterium 플랜 (Pro, Organization 또는 Enterprise). 무료 계정은 A2A에서 PLAN_REQUIRED 오류를 받습니다.
  2. magisterium.com 계정에 연결된 OAuth 2.0 액세스 토큰. A2A는 Magisterium MCP 서버와 동일한 OAuth 흐름을 사용합니다. 인증 엔드포인트, 토큰 엔드포인트, 동적 등록 엔드포인트는 https://www.magisterium.com/.well-known/oauth-authorization-server의 OAuth 메타데이터에서 확인하세요.
  3. 호출하고자 하는 스킬 — 전체 목록은 스킬을 참조하세요.

참고: API 콘솔에서 만든 장기 API 키는 Chat Completions, Search, News에서는 작동하지만 A2A에서는 유효하지 않습니다 — A2A는 OAuth로 발급된 사용자 토큰만 받습니다.

아래 예제가 자동으로 가져올 수 있도록 액세스 토큰을 환경 변수로 내보내세요:

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

1단계: 에이전트 탐색

엔드포인트를 호출하기 전에 공개 Agent Card를 가져와 사용 가능한 스킬을 확인하고 프로토콜 버전을 확인할 수 있습니다:

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

카드는 인증이 필요하지 않습니다. 오케스트레이터는 이를 1시간 동안 캐시할 수 있습니다 — 엔드포인트는 Cache-Control: public, max-age=3600을 설정합니다.

2단계: 첫 메시지 보내기

모든 A2A 작업은 단일 JSON-RPC 엔드포인트인 POST https://www.magisterium.com/api/v1/a2a를 통해 이루어집니다. 아래 예제는 catholic_qa 스킬에 대해 message/send를 호출합니다.

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"])

3단계: 응답 읽기

message/send는 kind: "task"인 Task 객체를 반환합니다. 동기 스킬 호출은 항상 두 가지 종료 상태 중 하나로 끝납니다:

  • status.state == "completed" — 결과는 result.artifacts에 있습니다. 각 artifact에는 artifactId, 선택적 name, 하나 이상의 parts (text, data 또는 file)가 있습니다.
  • status.state == "failed" — 실패 이유는 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": [] } }
        ]
      }
    ]
  }
}

4단계: 작업 가져오기 또는 취소하기

작업은 24시간 동안 저장되며 tasks/get을 사용하여 ID로 다시 가져올 수 있습니다:

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" }
    }'

작업을 중단해야 하는 경우 동일한 ID로 tasks/cancel을 호출하세요. 모든 Magisterium 스킬은 동기적으로 해결되므로 취소는 드문 재시도 시나리오에서만 유용합니다 — 이미 completed 또는 failed 상태인 작업은 취소할 수 없으며 INVALID_PARAMS를 반환합니다.

일반적인 오류

코드의미해결 방법
-32004인증되지 않음Authorization 헤더와 액세스 토큰이 유효하고 만료되지 않았는지 확인하세요.
-32005유료 플랜 필요magisterium.com/plan에서 계정을 업그레이드하세요.
-32002스킬을 찾을 수 없음metadata.skillId가 Agent Card에 나열된 ID와 일치하는지 확인하세요.
-32003속도 제한 초과재시도 전에 오류 data에 있는 retryAfter 초만큼 대기하세요.

모든 메서드와 오류 코드는 전체 API 참조를 확인하세요.