[Proposal]: New Repo: a2a-registry

[mindpower]

Repo Name: a2a-registry

Purpose: Normative Specification for Agent Discovery (REST APIs).

Why a new repo? This defines a Discovery Layer (Directory Services) that is architecturally distinct from the Transport Layer (A2A repo). The Registry API requires specialized read models (separating List vs. Search) and will evolve independently of the core wire protocol.

Scope (Phase 1):

• List API: A standard endpoint for fast, cacheable browsing and attribute-based filtering (e.g., by location, category, visibility)
• Search API: A standard endpoint for complex discovery, supporting both full-text keyword search and semantic (vector) queries.
• Response Data Model: Standardized JSON schemas for the Agent Object (endpoint, metadata, versioning) and search request/response models.

Current status:
We have an A2A registry spec proposal ready. Once we have new repo created, we can push the registry specs proposal there to start the discussion there.

Why not using A2A-samples? A "Registry Standard" is a dependency for samples, not a sample itself. Putting normative specs in a samples repo creates confusion for implementers later.

[darrelmiller]

@mindpower It is not clear to me why would would define a new "registry API" for A2A. Why do we need to define a "list" and "search" API specific to A2A? How is searching for an A2A Agent Card different than searching for an AI Card, or an MCP Server, or an HTTP API, or a NPM package? It just doesn't make sense to me that we define a new registry API for every new artifact we invent.

[jenish2917]

Hi team! 👋

I've been following this discussion and have built a production-ready A2A Agent Registry that addresses several points in this proposal. I'd love to contribute this to the community.

🚀 What I've Built

Repository: github.com/jenish2917/a2a-registry

A complete agent discovery and registration service with:

✅ Core Registry Server (TypeScript/Express)

• Full REST API for agent CRUD operations
• PostgreSQL with JSONB for flexible agent card storage
• Redis caching for high-performance lookups
• Docker deployment ready

✅ Semantic Search (Python/FastAPI) - NEW!

• Natural language agent discovery using sentence-transformers
• pgvector integration for vector similarity search
• Find agents by describing what you need: "translate text between languages"

✅ Python Client SDK

• Full API coverage with type hints (Pydantic)
• Semantic search support
• 18 unit tests passing

🔍 Semantic Search in Action

from a2a_registry import RegistryClient

client = RegistryClient("http://localhost:3000")

# Natural language search!
results = client.semantic_search("translate text between languages")

for agent in results:
    print(f"{agent.agent_id}: {agent.similarity_score:.2%} match")

📊 Architecture

Client ──► Registry Server (Port 3000) ──► PostgreSQL ◄── Semantic Search (Port 3001)
              (TypeScript/Express)          (+ pgvector)       (Python/FastAPI)

🛠️ Tech Stack

Component	Technology
Registry Server	TypeScript, Express.js, PostgreSQL, Redis
Semantic Search	Python, FastAPI, sentence-transformers, pgvector
Python SDK	httpx, Pydantic
Deployment	Docker Compose

📋 What's Next

I'm happy to:

1. Align the implementation with any specific requirements from the team
2. Add features based on community feedback
3. Contribute this as an official A2A registry or reference implementation
4. Help with documentation, examples, or SDK development

Would love to hear feedback on whether this aligns with the project's vision for agent discovery!

Best,
Jenish Barvaliya

• GitHub: @jenish2917
• LinkedIn: Jenish Barvaliya

[mindpower]

@darrelmiller

That is a fair challenge. To clarify, we are not trying to invent a new "storage" mechanism for artifacts, but rather a standard Discovery Protocol for active agents.

Here is why a generic artifact registry (like NPM or a generic HTTP list) doesn't solve the A2A interoperability problem:

1. Runtime Discovery vs. Build-time Indexing
Unlike NPM packages (which are downloaded by developers at build-time) or AI Cards (which are static metadata files), A2A Agents are live, dynamic endpoints.

• The Use Case: An Agent needs to programmatically ask: "Where is an active endpoint that can handle 'flight booking' and speaks A2A Protocol v1.0?"
• The Gap: A generic registry doesn't support this specific negotiation. We need a standard API contract so that an Agent built on Stack A can discover an Agent running on Stack B without custom integration code.

2. Capability-Based Search
Searching for an Agent is distinct from searching for a document. It requires specific filtering on:

• Protocol Version: "Only show agents compatible with v1.x."
• Attestations: "Only show agents with a valid trust score > 90."
• State: "Is this agent online/reachable right now?"
  Generic search APIs (like listing HTTP APIs) lack the semantic understanding of these Agent-specific fields, making automated discovery unreliable.

3. The "AI Card" Distinction
I view the AI Card as the Data Model (the payload), and this Registry API as the Transport (the query interface).

• Just having an AI Card format isn't enough; we need a standard way to fetch and filter those cards.
• Without a standard Registry API, every ecosystem will wrap AI Cards in their own proprietary search APIs, breaking the promise of an open, interoperable agent web.

Proposal Adjustment:
We can clarify that this registry specification defines the interface for Discovery, not the backend implementation. The backing store could indeed be an existing system (like an OCI registry or a vector DB), but the API surface exposed to Agents must be standardized for A2A to work globally.

Does that distinction make sense? We want to ensure an Agent can "lookup" another Agent regardless of who hosts the directory.

[mindpower]

@jenish2917 This is incredible execution! Great work getting a full stack (TS/Python/Vector) running so quickly! 🚀

Regarding the Spec/API: We actually have the draft Registry API specification defined and ready to go on our side. We are currently just blocked on the administrative step of getting the official repo created so we can share it publicly.
Proposed Plan (The "Convergence"): As soon as the a2a-registry repo is approved (hopefully days), here is how we can merge our efforts:

1. Push the Spec: we will initialize the repo and push our Draft OpenAPI/Swagger to a /spec folder.
2. You "Donate" the Implementation: You can then move your implementation code into a /reference or /implementation folder (aligned with the spec).
3. Review & Merge: We will review the PR to ensure the implementation matches the interface defined in the Spec, and then merge it in!

This is the perfect scenario: We can use your implementation to "stress test" the spec. If you find the spec makes it hard to implement the vector search you built, we fix the spec!

[darrelmiller]

We can clarify that this registry specification defines the interface for Discovery, not the backend implementation.

When I said, we don't need to define a new API, I meant "interface".

You can do everything that you are proposing by saying something like:

Agent registries should advertise a URI Template to enable clients to construct a search request. e.g.

https://agents.acme.com?q={query}{&minAttestation,supportedVersion}

Agent registries must support the query parameter, minAttestation and supportedVersion are optional and should only be included in the URI template if supported.

With this approach, an agent can be configured to search a registry by providing a URI template. The agent can resolve the search URL using one of the many available URI Template libraries.

Your AI Catalog proposal already defines a reasonable solution to what the response shape should be. I don't see a reason to define another JSON object.

[mindpower]

Thanks @darrelmiller for the reply!

You are 100% right on regarding the mechanism! URI Templates are the right way to handle the request construction. However, I want to clarify that standardizing that "Vocabulary" is exactly why we need this registry spec.
Even if we use URI Templates, we still need a normative definition for the keys to ensure interoperability:

• The Problem: If Registry A uses ?q={search} and Registry B uses ?k={keyword}, an Agent requires manual configuration for every new registry it encounters.
• The Solution: This spec acts as the "Dictionary" for your Template. We normatively define that query, minAttestation, and supportedVersion are the reserved standard keys so agents can work universally.

Regarding the Response Shape (and why AI-Catalog isn't enough on its own):
The AI-Catalog works perfectly for a static list of a few hundred agents (e.g., a single company's manifest). However, for a Global/Large Registry hosting thousands of agents, we run into two specific constraints that require a new API definition:

1. Pagination & Metadata (The Envelope):
   When a search returns 5,000 results, a raw array of AI Cards is insufficient. We need a standardized "Envelope" to handle pagination (nextPageToken, totalResults) and request metadata.
2. Vector Search Constraints (GET vs. POST):
   URI Templates (GET) work well for simple keywords, but they break down for Semantic/Vector Search. Vector embeddings and large context windows often exceed URL length limits. We need a standardized POST body structure to handle complex search intent (e.g., "Find agents similar to this finance agent that can handle the daily investment suggestions, here are more context (more long context) ").

Summary:
We are not defining a new Agent object model; we are wrapping the existing AI-Card.

• AI-Catalog: Static manifest (good for small, fixed lists).
• Registry API (This Proposal): Dynamic discovery, pagination, and vector search (required for network scale).

Agent registries should advertise a URI Template to enable clients to construct a search request. e.g.

https://agents.acme.com?q={query}{&minAttestation,supportedVersion}

Agent registries must support the query parameter, minAttestation and supportedVersion are optional and should only be included in the URI template if supported.

[liujuanjuan1984]

Seconded! I've already implemented support for consuming A2A providers in my team's project, and I'm currently struggling with the fact that there aren't enough A2A providers available. This registry is exactly what's missing.