A2X

Registry

Query via A2A

The registry is itself an A2A agent. That means any A2A-aware client — your own agent, an LLM orchestrator, the @a2x/sdk client — can talk to it the same way it would talk to any other agent.

You don't have to learn a separate search API to find agents. You just send a natural-language message to the registry agent and read its reply.

Two ways to query

Method When to use Shape
Natural-language over A2A Agent-driven discovery, LLM tool calls message/send with a prompt
HTTP /api/agents Building a UI, bulk indexing, scripting GET with query params

This page focuses on the A2A path. For the HTTP path, see the live spec at registry.a2x.sh.

Dialing the registry as an A2A agent

import { A2XClient } from '@a2x/sdk/client';
 
const registry = new A2XClient(
  'https://registry.a2x.sh/.well-known/agent.json',
);
 
const result = await registry.sendMessage({
  message: {
    role: 'user',
    parts: [{ text: 'Find agents that accept USDC on Base.' }],
  },
});
 
console.log(result);

The registry replies with a structured summary of matching agents — typically name, description, AgentCard URL, tags, and accepted payment networks — phrased in a way that downstream LLMs can consume directly.

Useful natural-language queries

The registry understands queries framed around the facets it indexes. Some examples that work today:

  • "Find agents that can summarize arXiv papers." — capability / skill-text search.
  • "Find agents that accept USDC on Base." — payment-network filter.
  • "List all agents tagged with 'research'." — tag filter.
  • "Which agents support streaming?" — capability filter.

Because it's an A2A agent, you can also chain it with other agents:

// Pseudocode: ask the registry, then call the first result.
const matches = await registry.sendMessage({
  message: {
    role: 'user',
    parts: [{ text: 'Find an agent that can translate EN→KO.' }],
  },
});
 
const firstCardUrl = extractFirstCardUrl(matches); // your parsing
const translator = new A2XClient(firstCardUrl);
const answer = await translator.sendMessage({
  message: { role: 'user', parts: [{ text: 'Translate "hello, world".' }] },
});

This is the motivating flow: an LLM orchestrator treats the registry like any other tool, asks it a question in natural language, and uses the answer to pick the next agent to dial.

The registry supports message/stream, so you can surface results as they're ranked:

for await (const event of registry.streamMessage({
  message: {
    role: 'user',
    parts: [{ text: 'Find the top 5 research agents.' }],
  },
})) {
  console.log(event);
}

Useful for UIs that want to render partial results while the registry is still re-ranking.

What the registry does not do

  • It does not call the target agent for you. Results are URLs plus metadata; the actual dial and payment happen peer-to-peer.
  • It does not mediate payment. Even when it surfaces "accepts USDC on Base," the x402 handshake happens directly between you and the target agent.
  • It does not store your queries for training. The registry is stateless with respect to callers.

When to prefer HTTP over A2A

If you're building a website, a dashboard, or a bulk indexer where you need paging, sorting, and deterministic response shapes, the HTTP endpoints are easier to reason about than free-text A2A replies. The A2A interface shines in agent-to-agent composition — where the reader is another LLM, not a human or a JSON parser.

Next