Conecta el inspector o el cliente A2A al origen del sitio (https://claix.dev), no a /a2a, para que resuelva la Agent Card en /.well-known/. El campo url / supportedInterfaces de la card apunta a https://claix.dev/a2a.

En cada POST /a2a envía la misma API key que en REST:

x-api-key: <TU_API_KEY>

Alternativa: Authorization: Bearer <TU_API_KEY>. Sin clave: JSON-RPC -32001 y HTTP 401. Clave inválida o cuenta inactiva: el mismo código. Límite: 60 peticiones por minuto por API key (HTTP 429, Retry-After).

La Agent Card es pública. Los mensajes, DataParts y cualquier card de un agente llamante se tratan como entrada no fiable y se validan antes de ejecutar nada.

La card declara name: Claix, la URL JSON-RPC, capabilities.pushNotifications: true, streaming: false y las 20 skills. El esquema de entrada de cada skill (parámetros OpenAPI, con file_base64 / file_path en lugar del file multipart) vive en la extensión https://claix.dev/a2a/extensions/openapi-skills.

Si el OpenAPI cambia, regenera las skills con npm run a2a:skills. No las edites a mano.

1. Descarga la Agent Card y elige una skill por id.
2. Envía POST https://claix.dev/a2a con method: "message/send".
3. Si ya tienes parámetros tipados, usa un DataPart JSON con "skill": "<id>". Se ejecuta de forma determinista, sin modelo de lenguaje.
4. Si solo tienes texto ambiguo, usa un TextPart. Gemini 3.6 Flash elige la skill y los argumentos a partir de los mismos esquemas.
5. Reutiliza el mismo contextId en mensajes siguientes para mantener el hilo (tabla conversaciones).

Métodos JSON-RPC habituales:

No hay message/stream / SSE. Las tareas largas no dejan la conexión abierta.

Ejemplo DataPart: {"skill":"extract-pdf","schema_id":"<uuid>","file_base64":"<base64>"}. El archivo multipart de la REST se envía aquí como file_base64 o file_path (URL https pública).

Una llamada correcta a message/send devuelve JSON-RPC result con un objeto Task (id, contextId, status.state, artefactos).

El resultado de negocio va en un artefacto JSON, no en SSE:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "<taskId>",
    "contextId": "<contextId>",
    "status": { "state": "completed" },
    "artifacts": [
      {
        "name": "list-schemas-result",
        "parts": [{ "kind": "data", "data": { "success": true, "schemas": [] } }]
      }
    ]
  }
}

Errores de protocolo (antes de crear la tarea):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32602, "message": "Invalid params: schema_id — …" }
}

Extraer un PDF, razonar en modo agente o preguntar a un space_id con muchos documentos no espera en la conexión HTTP. La primera respuesta queda en working. Configura un webhook A2A (tasks/pushNotificationConfig/set) para recibir la Task final (completed o failed) con el artefacto.

capabilities.pushNotifications está a true. No uses streaming SSE para estas operaciones.

El contextId de A2A identifica el hilo entre varias tareas. Claix lo guarda en conversaciones (context_id, user_id, last_task_id, last_activity_at). Reutiliza el mismo contextId en cada message/send del mismo diálogo.

Cada operación relevante del OpenAPI es una skill. Un DataPart debe incluir "skill": "<id>".

• SDK oficial TypeScript: @a2a-js/sdk
• Inspector: a2aproject/a2a-inspector contra https://claix.dev
• Cualquier cliente JSON-RPC A2A 0.3 / 1.0 con push notifications

MCP y A2A son interfaces distintas. MCP sigue en https://claix.dev/mcp. Este agente no llama al servidor MCP.