개방형 A2A (Agent-to-Agent) 프로토콜을 사용하여 AI 에이전트가 Magisterium AI를 탐색하고, 통신하고, 작업을 위임할 수 있도록 하세요.

왜 A2A인가?

MCP가 AI 도구에 Magisterium의 지식에 대한 접근을 제공한다면, A2A는 AI 에이전트가 Magisterium과 동료로서 협업할 수 있게 합니다. 오케스트레이션 에이전트는 Magisterium의 기능을 탐색하고, 작업을 전송하고, 구조화된 결과를 받을 수 있습니다 — 이 모든 것이 표준 JSON-RPC 인터페이스를 통해 이루어집니다.

유료 플랜이 필요합니다. A2A 엔드포인트는 Pro, Organization, Enterprise 플랜에서 사용할 수 있습니다. 무료 계정은 PLAN_REQUIRED (-32005) 오류를 받습니다. 현재 플랜 제한은 MCP 가격을 참조하세요 — A2A는 MCP와 동일한 속도 제한 풀을 공유합니다.

에이전트 탐색

Magisterium AI는 다음 위치에 공개 Agent Card를 게시합니다:

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

이는 외부 에이전트가 사용 가능한 스킬, 인증 요구사항 및 A2A 엔드포인트 URL을 탐색하는 방법입니다. 이 카드는 A2A 사양을 따르며 가져오는 데 인증이 필요하지 않습니다.

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

A2A 엔드포인트

모든 A2A 작업에 대한 JSON-RPC 엔드포인트는 다음과 같습니다:

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

모든 요청은 POST를 사용하며 Content-Type: application/json 헤더와 표준 JSON-RPC 2.0 엔벨로프를 포함해야 합니다.

기능

Agent Card는 다음 기능을 광고합니다:

인증

A2A는 Magisterium MCP 서버와 동일한 OAuth 2.0 사용자 토큰 인증을 사용합니다. A2A 엔드포인트를 호출하려면 magisterium.com에 계정이 있어야 합니다.

Magisterium은 https://www.magisterium.com/.well-known/oauth-authorization-server에 OAuth 2.0 메타데이터를 게시하며, 여기에는 인증 엔드포인트, 토큰 엔드포인트, 동적 클라이언트 등록 엔드포인트가 포함됩니다. OAuth 2.0 인증 코드 흐름(PKCE 포함)을 구현하는 클라이언트는 이 메타데이터에서 액세스 토큰을 얻을 수 있습니다. 표준 클라이언트 측 설정은 MCP 인증 문서를 참조하세요.

액세스 토큰을 얻은 후에는 모든 A2A 요청의 Authorization 헤더에 포함하세요:

Authorization: Bearer $MAGISTERIUM_TOKEN

API 콘솔에서 생성된 장기 API 키는 Chat Completions, Search, News 엔드포인트 전용입니다 — A2A에 대해 인증되지 않습니다. 대신 OAuth로 발급된 사용자 토큰을 사용하세요.

토큰이 누락되었거나 유효하지 않은 경우 UNAUTHORIZED (-32004) 오류가 반환됩니다.

빠른 예시

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

응답은 완료된 Task이며 답변과 인용은 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": [ /* ... */ ] } }
        ]
      }
    ]
  }
}

다음 단계

• 시작하기 — curl, Python 및 TypeScript로 첫 번째 A2A 요청을 진행해 보세요.
• 스킬 — A2A를 통해 노출되는 스킬의 전체 목록과 스킬별 입출력 구조.
• API 참조 — JSON-RPC 메서드, 오류 코드 및 작업 라이프사이클.