Todos los métodos se invocan mediante POST a https://www.magisterium.com/api/v1/a2a usando JSON-RPC 2.0. Toda solicitud debe incluir Authorization: Bearer $MAGISTERIUM_TOKEN (un token de usuario emitido por OAuth — consulta Autenticación) y Content-Type: application/json.

Métodos

message/send

Envía un mensaje a una habilidad y recibe una tarea completada. Todas las habilidades de Magisterium son síncronas — la respuesta contiene el estado terminal de la tarea (completed o failed), nunca un estado intermedio working.

Parámetros:

Campo	Tipo	Obligatorio	Descripción
message	Message	Sí	El mensaje del usuario con partes y metadatos opcionales.
message.role	string	Sí	Debe ser "user".
message.messageId	string	Sí	ID único para este mensaje.
message.kind	string	Sí	Debe ser "message".
message.parts	Part[]	Sí	Al menos una parte (text o data).
message.metadata.skillId	string	No	Habilidad que se invocará. Por defecto es catholic_qa.
message.contextId	string	No	ID de contexto opcional para agrupar tareas relacionadas. Si se omite, el servidor genera uno.
configuration	object	No	Reservado para uso futuro.

Devuelve: un objeto Task con kind: "task".

tasks/get

Recupera una tarea creada previamente por su ID.

Parámetros:

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	El ID de la tarea devuelto por message/send.

Devuelve: el objeto Task, o un error TASK_NOT_FOUND si ha caducado o no existe. Las tareas se almacenan durante 24 horas.

tasks/cancel

Cancela una tarea si se encuentra en un estado cancelable. Como todas las habilidades se resuelven de forma síncrona, la mayoría de las tareas ya están en un estado terminal (completed / failed) cuando se devuelve la respuesta — intentar cancelar una tarea terminal devuelve INVALID_PARAMS con un mensaje Invalid state transition.

Parámetros:

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	El ID de la tarea que se va a cancelar.

Devuelve: el objeto Task actualizado con status.state: "canceled".

Ciclo de vida de la tarea

Las habilidades de Magisterium se ejecutan de forma síncrona, por lo que una tarea solo se persiste en almacenamiento después de que la habilidad finaliza — siempre en un estado terminal. Los estados submitted y working forman parte de la especificación A2A más amplia, pero la implementación de Magisterium nunca los produce; solo observarás uno de los tres estados terminales que aparecen a continuación.

Estado	Significado
completed	Terminal — los resultados están en artifacts. Devuelto por message/send cuando la habilidad finaliza correctamente.
failed	Terminal — status.message contiene el motivo del fallo. Devuelto por message/send cuando la habilidad lanza una excepción.
canceled	Terminal — solo es alcanzable invocando tasks/cancel sobre una tarea no terminal. Como las tareas ya están en un estado terminal cuando message/send devuelve, en la práctica la cancelación se rechaza con INVALID_PARAMS para cualquier tarea sobre la que tengas un identificador.

Cada tarea lleva además:

• contextId — un identificador de agrupación que puedes reutilizar entre mensajes de seguimiento para vincular tareas relacionadas.
• history — la lista ordenada de mensajes del usuario y del agente que generaron los artefactos de la tarea.

Códigos de error

Código	Nombre	Descripción
-32700	Parse error	Cuerpo JSON inválido.
-32600	Invalid request	Faltan los campos jsonrpc, method o id.
-32601	Method not found	Método JSON-RPC desconocido.
-32602	Invalid params	Parámetros ausentes o inválidos (también se devuelve para transiciones de estado inválidas en tasks/cancel).
-32603	Internal error	Fallo inesperado en el servidor.
-32001	Task not found	El ID de la tarea no existe o ha caducado.
-32002	Skill not found	skillId desconocido en los metadatos del mensaje.
-32003	Rate limit exceeded	Demasiadas solicitudes. Revisa retryAfter (segundos) en el data del error.
-32004	Unauthorized	Falta el token Bearer o es inválido.
-32005	Paid plan required	A2A requiere un plan Pro, Organización o Empresa.

El estado HTTP refleja la clase del error: 401 para UNAUTHORIZED, 403 para PLAN_REQUIRED, 429 para RATE_LIMITED y 200 para el resto de errores JSON-RPC (según la convención JSON-RPC de devolver 200 con un cuerpo error).

Límites de uso

A2A comparte el mismo grupo de límites de uso que MCP — consulta los Precios de MCP para ver los topes de solicitudes de cada plan.

Se aplican dos variantes:

• Predeterminada — se aplica a document_search, document_fetch, liturgical_readings y saints_of_the_day.
• Intensiva — se aplica únicamente a catholic_qa, porque ejecuta una canalización de respuesta respaldada por un LLM. Esta variante utiliza un tope más estricto y bajo.

Cuando alcanzas un límite, el objeto data del error contiene retryAfter en segundos. Los llamadores deben esperar ese intervalo antes de reintentar.

CORS

El endpoint responde a solicitudes preflight OPTIONS y devuelve cabeceras CORS permisivas (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), de modo que A2A puede invocarse desde orquestadores basados en navegador sin necesidad de un proxy.