Magisterium AI

Rochpi
Vantto kor:

सुरुवात करप

ह्या मार्गदर्शका तुमी Magisterium A2A एंडपॉइंटाक तुमची पयली विनंती करप, निकाल कार्य मेळोवप, आनी संरचित प्रतिसाद वाचपाच्या मार्गान व्हरता.

पूर्व गरजो

  1. एक पेड Magisterium प्लॅन (Pro, Organization, वा Enterprise). फुकट खात्यांक A2A-थावन PLAN_REQUIRED त्रुटी मेळटली.
  2. तुमच्या magisterium.com खात्याशी जोडिल्लो एक OAuth 2.0 access टोकन. A2A Magisterium MCP सर्व्हर-सारकेंच OAuth फ्लो वापरता; https://www.magisterium.com/.well-known/oauth-authorization-server-वयर OAuth metadata-थावन authorization, token, आनी dynamic-registration endpoints शोधात.
  3. तुमकां कॉल करूंक जाय तीं कौशल्यां — पुराय वळेरीखातीर कौशल्यां पळयात.

सावधान: API Console-त तयार केल्ल्यो दीर्गकाळिक API-यो Chat Completions, Search, आनी News-खातीर काम करतात, पूण त्यो A2A-खातीर वैध ना — A2A फकत OAuth-न जारी केल्ले वापरकर्ता टोकन स्वीकारता.

सकयल्यो उदाहरणां स्वयंचालित रितीन तिका घेवपाक तुमचो access टोकन एका environment variable रुपान export करा:

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

पांवडो 1: एजंट शोधात

एंडपॉइंट कॉल करच्यापयलीं, कोणचीं कौशल्यां उपलब्ध आसात तें पळोवपाक आनी प्रोटोकॉल आवृत्तीची खातरजमा करपाक तुमी सार्वजनिक Agent Card घेवूं शकतात:

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

कार्डाक कसलोच प्रमाणीकरण गरजेचो ना. ऑर्केस्ट्रेटर तिका एका वरा खातीर cache करूं शकतात — एंडपॉइंट 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 ऑब्जेक्ट परत करता. एक synchronous कौशल्य कॉल सदांच दोन टर्मिनल स्थितींपैकीं एकांत सोंपता:

  • 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 कौशल्यां synchronous रुपान सोडयतात म्हणून, रद्दकरण खंयच्या तरी दुर्मीळ पुनःप्रयत्न परिस्थितींतूच उपयोगी — आदीं completed वा failed जाल्लें कार्य रद्द करूंक मेळचें ना आनी तें INVALID_PARAMS परत करतलें.

सामान्य त्रुटी

कोडअर्थउपाय
-32004UnauthorizedAuthorization हेडर आनी access token वैध आसा आनी मुदत सोपूंक ना हें तपासात.
-32005Paid plan requiredmagisterium.com/plan-चेर तुमचे खातें अपग्रेड करात.
-32002Skill not foundAgent Card-त वळेरींत आशिल्ल्या ID-शीं metadata.skillId जुळटा तें पडताळून पळयात.
-32003Rate limit exceededपरत प्रयत्न करच्यापयलीं retryAfter सेकंद (त्रुटीच्या data-त उपलब्ध) सांबाळा.

दरेक पद्दत आनी त्रुटी कोडाखातीर पुराय API संदर्भ पळयात.