Antes de enviar trabajo, descarga la Agent Card. Es un JSON público (sin API key) que dice quién es Claix, dónde hay que llamar y qué skills existen.

Descarga la card:

curl -sS "https://claix.dev/.well-known/agent.json"

También está en https://claix.dev/.well-known/agent-card.json. En el JSON fíjate en:

• url / supportedInterfaces: la URL a la que debes hacer POST (https://claix.dev/a2a).
• skills: lista de habilidades. Cada una tiene id, nombre, descripción y ejemplos de payload.
• capabilities.pushNotifications: true. Las tareas largas avisan a un webhook; no hay streaming SSE.

Si usas un cliente o inspector A2A, conéctalo al origen https://claix.dev (no a /a2a) para que resuelva solo la card en /.well-known/.

Cada POST /a2a lleva la misma API key que el resto de Claix. La Agent Card no.

Opción recomendada:

x-api-key: <TU_API_KEY>

Alternativa:

Authorization: Bearer <TU_API_KEY>

Con una de las dos basta. Sin clave o con clave inválida: HTTP 401 y JSON-RPC -32001. Límite: 60 peticiones por minuto por API key (HTTP 429, cabecera Retry-After).

Todas las operaciones van al mismo sitio: POST https://claix.dev/a2a, Content-Type: application/json. El cuerpo es un sobre JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": { }
  }
}

Campos del sobre:

Dentro de params.message:

Hay dos formas de pedir trabajo. Si ya sabes la skill y los parámetros, envía un DataPart. Si solo tienes una instrucción en lenguaje natural, envía un TextPart.

Es la forma más predecible. Una parte kind: "data" con un objeto JSON que incluye "skill" (el id de la Agent Card) y el resto de campos que esa skill espera.

Ejemplo mínimo — listar schemas:

curl -X POST "https://claix.dev/a2a" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <TU_API_KEY>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "messageId": "msg-list-schemas",
        "kind": "message",
        "parts": [
          { "kind": "data", "data": { "skill": "list-schemas" } }
        ]
      }
    }
  }'

Ejemplo con archivo — extraer un PDF. En A2A no hay multipart: el archivo va en file_base64 (Base64 o data URL) o en file_path (URL https pública).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "msg-extract-pdf",
      "kind": "message",
      "parts": [
        {
          "kind": "data",
          "data": {
            "skill": "extract-pdf",
            "schema_id": "<uuid-de-tu-schema>",
            "file_base64": "JVBERi0xLjQK..."
          }
        }
      ]
    }
  }
}

Si falta un dato que puedes completar (por ejemplo el schema o el archivo), la tarea queda en input-required en lugar de fallar. Envía otro message/send en el mismo contextId con el campo que falta. Si el id de skill no existe o un parámetro tiene un formato inválido, recibes JSON-RPC -32602 (Invalid params) sin crear la tarea.

Si aún no tienes los parámetros tipados, envía texto. Claix interpreta la petición, elige la skill y rellena los argumentos.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "msg-nl",
      "kind": "message",
      "parts": [
        {
          "kind": "text",
          "text": "Lista mis schemas y dime cuál uso para extraer facturas PDF."
        }
      ]
    }
  }
}

Úsalo para explorar o para agentes que hablan en lenguaje natural. Cuando ya conozcas skill y los campos, prefiere un DataPart: es más estable y no depende de cómo se formule la frase.

Una llamada correcta no devuelve el JSON de negocio en la raíz. El result es una Task A2A. El dato útil está en artifacts.

{
  "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": [] }
          }
        ]
      }
    ]
  }
}

Guarda result.id (la tarea) y result.contextId (el hilo). Mira result.status.state:

Para consultar una tarea ya creada:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tasks/get",
  "params": { "id": "<taskId>" }
}

Para cancelarla: method: "tasks/cancel" con el mismo params.id.

Si el sobre JSON-RPC o la autenticación fallan, no hay Task. Recibes error:

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

Extraer un PDF, usar Modo agente o preguntar a un espacio con muchos documentos no espera en la conexión HTTP. La primera respuesta suele llegar con status.state: "working". No uses SSE: streaming está desactivado.

Registra un webhook A2A para recibir la Task final (completed o failed) con el artefacto. Puedes enviarlo junto al mensaje:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "msg-extract-pdf",
      "kind": "message",
      "parts": [
        {
          "kind": "data",
          "data": {
            "skill": "extract-pdf",
            "schema_id": "<uuid>",
            "file_base64": "JVBERi0xLjQK..."
          }
        }
      ]
    },
    "configuration": {
      "pushNotificationConfig": {
        "url": "https://tu-agente.ejemplo/a2a/push",
        "token": "opcional-para-autenticar-el-webhook"
      }
    }
  }
}

O registrarlo después, cuando ya tengas el taskId:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tasks/pushNotificationConfig/set",
  "params": {
    "id": "<taskId>",
    "pushNotificationConfig": {
      "url": "https://tu-agente.ejemplo/a2a/push"
    }
  }
}

Claix hará POST a esa URL con la Task cuando termine. Tu endpoint debe aceptar el payload A2A de notificación.

Cada Task trae un contextId. Es el identificador del diálogo entre tu agente y Claix. Si omites el campo, Claix asigna uno nuevo. Si lo reutilizas en el siguiente message/send, sigues la misma conversación (por ejemplo: listar schemas → extraer con el schema_id que te acaba de devolver).

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "msg-follow-up",
      "contextId": "el-mismo-contextId-de-antes",
      "kind": "message",
      "parts": [
        {
          "kind": "text",
          "text": "Usa ese schema y extrae el PDF que te paso ahora."
        }
      ]
    }
  }
}

Un contextId nuevo = conversación nueva. El mismo valor = mismo hilo. No lo mezcles entre cuentas o agentes distintos.

El DataPart debe llevar "skill": "<id>". Los ids y un resumen salen de la Agent Card; esta tabla es la misma lista:

Los ejemplos de cada skill (campos JSON concretos) están en la Agent Card, en skills[].examples.

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

• SDK 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 sigue en https://claix.dev/mcp. REST sigue en las rutas de la API. Son interfaces distintas; elige una por integración.