1. Apicurio Registry
  2. AI agents
  3. What is an agent registry?

What is an agent registry?

An agent registry is a catalog of AI agents and the capabilities they expose. Each agent publishes a machine-readable description of itself (in the A2A protocol, an agent card), and other agents or orchestrators query the registry to find an agent that has the skill, input format or capability they need.

Why agents need a registry

A single agent can hard-code the addresses of the tools it calls. A system of many agents cannot: agents are added, upgraded and retired independently, and an orchestrator has to choose among them at runtime. Without a registry, every caller keeps its own copy of what each agent can do, and those copies drift. An agent registry gives the system one source of truth, the same role a service registry plays for microservices and a schema registry plays for event-driven systems.

What an agent card contains

The Agent2Agent (A2A) protocol defines the agent card, a JSON document that describes an agent. A card typically includes:

  • the agent's name, description, version and provider;
  • the URL where the agent can be reached;
  • its skills, the tasks it can perform;
  • its capabilities, such as streaming or push notifications;
  • the input and output modes it accepts, such as text or application/json;
  • the authentication it requires.

By convention, an agent serves its own card at /.well-known/agent.json. A registry collects many cards in one place so they can be searched.

Agent registry vs. service registry vs. schema registry

Service registrySchema registryAgent registry
StoresNetwork locations of service instancesData and API contractsAgent cards: identity, skills, capabilities
Queried byLoad balancers, clientsProducers, consumers, CIOrchestrators and other agents
Typical question"Where is service X?""What does this message look like?""Which agent can do task Y?"
Change controlHealth checksCompatibility rulesVersioning and validation of cards

Apicurio Registry as an agent registry

Apicurio Registry stores agent cards as AGENT_CARD artifacts, so each card is validated and versioned alongside your other schemas and API definitions. With A2A support enabled, it provides:

  • GET /.well-known/agents, which searches registered cards by name (with * wildcards), skill, capability, inputMode and outputMode;
  • GET /.well-known/agents/{groupId}/{artifactId}, which returns a single card;
  • GET /.well-known/agent.json, Apicurio Registry's own agent card, which advertises skills such as schema validation, schema search and compatibility checking;
  • visibility labels that control which cards each caller can see when authentication is enabled.

Example search for agents that can translate and support streaming:

curl "http://localhost:8080/.well-known/agents?skill=translation&capability=streaming:true"
A2A support is experimental and disabled by default. Enable it with APICURIO_FEATURES_EXPERIMENTAL_ENABLED=true and APICURIO_A2A_ENABLED=true.

Learn more