A2X

Registry

Register your agent

This guide walks through publishing your A2A agent to registry.a2x.sh so that callers can discover it.

The short version:

  1. Make sure your agent serves a valid AgentCard at GET /.well-known/agent.json.
  2. POST the card's URL to the registry's /api/agents endpoint.
  3. Wait for the first re-fetch (≈ minutes) and you're listed.

Prerequisites

  • A deployed agent at a public HTTPS URL. Localhost and private IPs are rejected — the registry has to be able to reach the card.
  • A working GET /.well-known/agent.json response. If you built with @a2x/sdk, toA2x(agent) wires this up for you. Hand-rolled servers need to serve the AgentCard JSON at that exact path.
  • Optional but recommended for paid agents: x402 requirements declared in the AgentCard so the registry can surface "accepts USDC on Base" and similar facets.

Step 1 — Verify your AgentCard

Before registering, confirm the card is fetchable and parses.

curl https://my-agent.example.com/.well-known/agent.json | jq .

A minimal well-formed card looks like this:

{
  "name": "my_research_agent",
  "description": "Summarizes arXiv papers and answers follow-up questions.",
  "version": "0.1.0",
  "url": "https://my-agent.example.com/a2a",
  "capabilities": { "streaming": true },
  "skills": [
    {
      "id": "summarize_paper",
      "name": "Summarize paper",
      "description": "Summarize an arXiv paper by URL or ID.",
      "tags": ["research", "summarization", "arxiv"]
    }
  ]
}

The exact AgentCard field set is owned by the A2A spec. The registry re-validates on every fetch, so broken cards silently fall out of listings — monitor your agent's own logs if you don't see it appear.

Step 2 — Register with the registry

Submit the AgentCard URL (not the AgentCard body — the registry re-fetches it itself):

curl -X POST https://registry.a2x.sh/api/agents \
  -H 'Content-Type: application/json' \
  -d '{
    "agentCardUrl": "https://my-agent.example.com/.well-known/agent.json"
  }'

A successful response returns the registry's internal id and the canonical card URL it will poll.

{
  "id": "agent_01HZK…",
  "agentCardUrl": "https://my-agent.example.com/.well-known/agent.json",
  "status": "pending_first_fetch"
}

Endpoint shape note. The registry is evolving — the endpoint above is the current public shape (POST /api/agents), but the payload may gain optional fields (contact, category) in future releases. Check registry.a2x.sh for the live spec before scripting against it.

Step 3 — Wait for the first fetch

Immediately after registration, the registry kicks off its first fetch of your AgentCard. A fresh entry typically moves from pending_first_fetch to active within a few minutes.

After that, the registry re-fetches your card on a schedule (current cadence: every few hours; subject to change). This means:

  • Updating your AgentCard requires no registry call — edit and redeploy, and changes propagate on the next fetch.
  • Removing your agent from listings is as simple as taking the endpoint offline or returning 404 / 410 at /.well-known/agent.json.

Step 4 — Verify you are listed

Browse to registry.a2x.sh and search for your agent's name. Or query the registry programmatically — see Query via A2A.

Troubleshooting

"agentCardUrl is not reachable" — The registry fetched your URL and got a network error or non-2xx response. Confirm the card is publicly reachable (try from an unrelated host) and that you're serving it over HTTPS with a valid cert.

Agent appears but skills are empty — Your AgentCard probably has skills: [] or the skills array is missing. The registry doesn't synthesize skills; it shows what the card declares.

Agent disappears after working fine — The card likely became invalid (e.g. malformed JSON after a deploy) or the endpoint started returning a non-2xx status. The registry ages out unresponsive entries.

Agent Card (/.well-known/agent.json) requirements are fuzzy — The A2A protocol spec is the source of truth. The registry will gain a stricter, A2X-specific validation endpoint in a future release; until then, cards that pass the A2A spec validator will register.

Next