Point the inspector or A2A client at the site origin (https://claix.dev), not at /a2a, so it can resolve the Agent Card under /.well-known/. The card url / supportedInterfaces fields point to https://claix.dev/a2a.

On every POST /a2a send the same API key as REST:

x-api-key: <YOUR_API_KEY>

Alternative: Authorization: Bearer <YOUR_API_KEY>. Missing key: JSON-RPC -32001 and HTTP 401. Invalid key or inactive account: the same code. Limit: 60 requests per minute per API key (HTTP 429, Retry-After).

The Agent Card is public. Messages, DataParts, and any caller agent card are untrusted input and are validated before any business logic runs.

The card declares name: Claix, the JSON-RPC URL, capabilities.pushNotifications: true, streaming: false, and the 20 skills. Each skill's input schema (OpenAPI parameters, with file_base64 / file_path instead of multipart file) lives in the https://claix.dev/a2a/extensions/openapi-skills extension.

If OpenAPI changes, regenerate skills with npm run a2a:skills. Do not edit them by hand.

1. Fetch the Agent Card and pick a skill by id.
2. POST https://claix.dev/a2a with method: "message/send".
3. If you already have typed parameters, send a JSON DataPart with "skill": "<id>". That path is deterministic — no language model.
4. If you only have ambiguous text, send a TextPart. Gemini 3.6 Flash chooses the skill and arguments from the same schemas.
5. Reuse the same contextId on follow-up messages to keep the thread (stored in conversaciones).

Common JSON-RPC methods:

There is no message/stream / SSE. Long tasks do not keep the HTTP connection open.

DataPart example: {"skill":"extract-pdf","schema_id":"<uuid>","file_base64":"<base64>"}. REST multipart file becomes file_base64 or file_path (public https URL).

A successful message/send returns a JSON-RPC result Task (id, contextId, status.state, artifacts).

Business output is a JSON artifact, not 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": [] } }]
      }
    ]
  }
}

Protocol errors (before a task is created):

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

Extracting a PDF, agent-mode reasoning, or querying a space_id with many documents does not wait on the HTTP connection. The first response stays working. Set an A2A webhook (tasks/pushNotificationConfig/set) to receive the final Task (completed or failed) with the artifact.

capabilities.pushNotifications is true. Do not use SSE streaming for these operations.

The A2A contextId is the thread across tasks. Claix stores it in conversaciones (context_id, user_id, last_task_id, last_activity_at). Reuse the same contextId on every message/send in that dialogue.

Each relevant OpenAPI operation is a skill. A DataPart must include "skill": "<id>".

• Official TypeScript SDK: @a2a-js/sdk
• Inspector: a2aproject/a2a-inspector against https://claix.dev
• Any A2A 0.3 / 1.0 JSON-RPC client with push notifications

MCP and A2A are separate interfaces. MCP remains at https://claix.dev/mcp. This agent does not call the MCP server.