Alle Methoden werden über POST an https://www.magisterium.com/api/v1/a2a mit JSON-RPC 2.0 aufgerufen. Jede Anfrage muss Authorization: Bearer $MAGISTERIUM_TOKEN (ein über OAuth ausgestelltes Benutzer-Token — siehe Authentifizierung) und Content-Type: application/json enthalten.

Methoden

message/send

Sendet eine Nachricht an einen Skill und empfängt eine abgeschlossene Aufgabe. Alle Magisterium-Skills sind synchron — die Antwort enthält den Endzustand der Aufgabe (completed oder failed), niemals einen zwischenzeitlichen working-Status.

Parameter:

Feld	Typ	Erforderlich	Beschreibung
message	Message	Ja	Die Benutzernachricht mit Parts und optionalen Metadaten.
message.role	string	Ja	Muss "user" sein.
message.messageId	string	Ja	Eindeutige ID für diese Nachricht.
message.kind	string	Ja	Muss "message" sein.
message.parts	Part[]	Ja	Mindestens ein Part (text oder data).
message.metadata.skillId	string	Nein	Aufzurufender Skill. Standard ist catholic_qa.
message.contextId	string	Nein	Optionale Kontext-ID zum Gruppieren verwandter Aufgaben. Wird sie weggelassen, generiert der Server eine.
configuration	object	Nein	Reserviert für die zukünftige Verwendung.

Rückgabe: Ein Task-Objekt mit kind: "task".

tasks/get

Abruf einer zuvor erstellten Aufgabe anhand ihrer ID.

Parameter:

Feld	Typ	Erforderlich	Beschreibung
id	string	Ja	Die von message/send zurückgegebene Aufgaben-ID.

Rückgabe: Das Task-Objekt oder ein TASK_NOT_FOUND-Fehler, wenn es abgelaufen ist oder fehlt. Aufgaben werden 24 Stunden lang gespeichert.

tasks/cancel

Bricht eine Aufgabe ab, wenn sie sich in einem abbrechbaren Zustand befindet. Da alle Skills synchron aufgelöst werden, befinden sich die meisten Aufgaben bereits in einem Endzustand (completed / failed), wenn die Antwort zurückkehrt — der Versuch, eine Aufgabe im Endzustand abzubrechen, gibt INVALID_PARAMS mit einer Invalid state transition-Meldung zurück.

Parameter:

Feld	Typ	Erforderlich	Beschreibung
id	string	Ja	Die abzubrechende Aufgaben-ID.

Rückgabe: Das aktualisierte Task-Objekt mit status.state: "canceled".

Aufgaben-Lebenszyklus

Magisteriums Skills laufen synchron, sodass eine Aufgabe erst nach Abschluss des Skills im Speicher persistiert wird — immer in einem Endzustand. Die Zustände submitted und working sind Teil der umfassenderen A2A-Spezifikation, werden aber von der Magisterium-Implementierung niemals erzeugt; Sie werden immer nur einen der drei unten aufgeführten Endzustände beobachten.

Zustand	Bedeutung
completed	Endzustand — die Ergebnisse befinden sich in artifacts. Wird von message/send zurückgegeben, wenn der Skill erfolgreich abgeschlossen wird.
failed	Endzustand — status.message enthält den Fehlergrund. Wird von message/send zurückgegeben, wenn der Skill eine Ausnahme wirft.
canceled	Endzustand — nur erreichbar, indem tasks/cancel für eine Aufgabe in einem Nicht-Endzustand aufgerufen wird. Da Aufgaben bereits einen Endzustand haben, wenn message/send zurückkehrt, wird der Abbruch in der Praxis für jede Aufgabe, auf die Sie einen Handle haben, mit INVALID_PARAMS abgelehnt.

Jede Aufgabe trägt außerdem:

• contextId — ein Gruppierungsbezeichner, den Sie über Folgenachrichten hinweg wiederverwenden können, um verwandte Aufgaben zu verknüpfen.
• history — die geordnete Liste der Benutzer- und Agentennachrichten, die die Artefakte der Aufgabe erzeugt haben.

Fehlercodes

Code	Name	Beschreibung
-32700	Parse error	Ungültiger JSON-Body.
-32600	Invalid request	Fehlende Felder jsonrpc, method oder id.
-32601	Method not found	Unbekannte JSON-RPC-Methode.
-32602	Invalid params	Fehlende oder ungültige Parameter (wird auch für ungültige tasks/cancel-Zustandsübergänge zurückgegeben).
-32603	Internal error	Unerwarteter serverseitiger Fehler.
-32001	Task not found	Aufgaben-ID existiert nicht oder ist abgelaufen.
-32002	Skill not found	Unbekannte skillId in den Nachrichten-Metadaten.
-32003	Rate limit exceeded	Zu viele Anfragen. Prüfen Sie retryAfter (Sekunden) im Fehler-data.
-32004	Unauthorized	Fehlender oder ungültiger Bearer-Token.
-32005	Paid plan required	A2A erfordert einen Pro-, Organisation- oder Enterprise-Plan.

Der HTTP-Status entspricht der Fehlerklasse: 401 für UNAUTHORIZED, 403 für PLAN_REQUIRED, 429 für RATE_LIMITED und 200 für alle anderen JSON-RPC-Fehler (gemäß der JSON-RPC-Konvention, 200 mit einem error-Body zurückzugeben).

Rate-Limits

A2A teilt sich denselben Rate-Limit-Pool wie MCP — siehe MCP-Preise für die Anfragekontingente pro Plan.

Zwei Varianten werden erzwungen:

• Standard — gilt für document_search, document_fetch, liturgical_readings und saints_of_the_day.
• Expensive — gilt nur für catholic_qa, da dieser eine LLM-gestützte Antwort-Pipeline ausführt. Diese Variante verwendet ein strengeres, niedrigeres Limit.

Wenn Sie ein Limit erreichen, enthält das Fehler-data-Objekt retryAfter in Sekunden. Aufrufer sollten für dieses Intervall zurückweichen, bevor sie es erneut versuchen.

CORS

Der Endpunkt antwortet auf OPTIONS-Preflight-Anfragen und liefert permissive CORS-Header (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), sodass A2A aus browserbasierten Orchestratoren ohne Proxy aufgerufen werden kann.