@a2a-relay/registry

Open agent registry — register, discover, and search A2A agents.

Part of Agent Relay — the open infrastructure for the agent economy.

Install

npm install @a2a-relay/registry

Quick Start

import { AgentRegistry } from '@a2a-relay/registry';

const registry = new AgentRegistry({
  port: 3002,
  dataFile: './agents.json',   // persistent storage
  healthCheck: true,            // periodically verify agents are reachable
  adminToken: 'my-secret',     // for delete operations
});

registry.listen();

API

Register an Agent

Agents register by providing their URL. The registry fetches the Agent Card automatically.

# Auto-fetch Agent Card from well-known URL
curl -X POST http://localhost:3002/agents \
  -H 'Content-Type: application/json' \
  -d '{"url": "http://my-agent.com"}'

# Or provide the Agent Card directly
curl -X POST http://localhost:3002/agents \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "http://my-agent.com",
    "agentCard": {
      "name": "My Agent",
      "url": "http://my-agent.com/a2a/jsonrpc",
      "skills": [{ "id": "greet", "name": "Greeting", "description": "Say hello" }]
    }
  }'

Response:

{ "id": "uuid", "name": "My Agent", "status": "registered", "skills": 1 }

Re-registering the same URL updates the existing entry.

Search Agents

# Free-text search
curl 'http://localhost:3002/agents/search?q=weather'

# Search by tags
curl 'http://localhost:3002/agents/search?tags=weather,forecast'

# Search by skill ID
curl 'http://localhost:3002/agents/search?skill=diagnose'

# Combine + paginate
curl 'http://localhost:3002/agents/search?q=code&limit=10&offset=0'

Response:

{
  "total": 42,
  "count": 1,
  "offset": 0,
  "agents": [{
    "id": "uuid",
    "name": "Code Reviewer",
    "description": "Reviews code and suggests improvements",
    "url": "https://code-agent.com",
    "skills": [...],
    "tags": ["code", "review"],
    "status": "online",
    "registeredAt": "2025-01-01T00:00:00Z"
  }]
}

List All Agents

curl http://localhost:3002/agents
curl 'http://localhost:3002/agents?limit=10&offset=20'

Get a Specific Agent

curl http://localhost:3002/agents/<id>

Remove an Agent

# Admin delete (requires admin token)
curl -X DELETE http://localhost:3002/agents/<id> \
  -H 'Authorization: Bearer my-secret'

# Self-unregister (by URL)
curl -X POST http://localhost:3002/agents/unregister \
  -H 'Content-Type: application/json' \
  -d '{"url": "http://my-agent.com"}'

Stats & Health

# Registry health
curl http://localhost:3002/health

# Detailed stats
curl http://localhost:3002/stats

Features

• Auto-discovery — register by URL, the registry fetches your Agent Card
• Full-text search — search across names, descriptions, tags, skills
• Tag & skill filtering — find agents by capability
• Health checks — periodically verifies registered agents are reachable
• File persistence — survives restarts (or run in-memory only)
• Pagination — handles large registries
• Self-unregister — agents can remove themselves
• Admin API — protected delete operations

Standalone Server

REGISTRY_PORT=3002 DATA_FILE=./agents.json ADMIN_TOKEN=secret node dist/standalone.js

Programmatic Use

import { AgentRegistry } from '@a2a-relay/registry';

const registry = new AgentRegistry({ port: 3002 });
await registry.listen();

// Access the store directly
const store = registry.getStore();
const agents = store.search({ q: 'weather', tags: ['forecast'] });

Related

• @a2a-relay/server — build A2A agents
• @a2a-relay/client — discover and talk to agents
• Agent Relay — the full project

License

MIT