Skip to content

project.md

Latest commit

 

History

History
112 lines (78 loc) · 5.3 KB

project.md

File metadata and controls

112 lines (78 loc) · 5.3 KB

Of course. Here is a comprehensive project specification that consolidates our entire conversation into a formal plan.

## Project Specification: A2A Registry

  • Project Name: A2A Registry
  • Version: 1.0
  • Date: August 9, 2025
  • Domain: a2aregistry.org

1. Executive Summary

The A2A Registry will be a community-driven, open-source directory of AI agents designed to solve the critical problem of agent discovery. Using a "Git as a Database" model, the project will leverage GitHub for data submission, validation, and hosting. The registry will be accessible to humans via a public website (www.a2aregistry.org) and to agents programmatically via a static API endpoint and a dedicated Python client library.

The core principle is to provide a simple, transparent, and robust platform that fosters an ecosystem of interoperable AI agents.

2. Core Components & Architecture

The project consists of three main, tightly integrated components.

2.1. The Git Repository (Source of Truth)

The single GitHub monorepo is the heart of the project.

  • Platform: GitHub
  • Structure:
    • /.github/workflows/: Contains GitHub Actions for all automation.
    • /agents/: The "database." A flat directory where each .json file is a unique agent entry.
    • /docs/: Contains the static files for the website hosted on GitHub Pages.
    • /client-python/: The source code for the Python client library.
  • Agent Data Schema: Each agent file in /agents/ must be a JSON object validating against a defined schema. Required fields include:
    • name (string): The agent's display name.
    • description (string): A brief explanation of the agent's purpose.
    • author (string): The name or handle of the creator.
    • wellKnownURI (string, URI): The /.well-known/agent-card.json URI for validation.
    • capabilities (array of strings): A list of tasks the agent can perform (e.g., "image-generation", "data-analysis").

2.2. The Automation Pipeline (CI/CD)

All validation and publishing is handled automatically by GitHub Actions.

  • Workflow 1: PR Validation (validate-pr.yml)
    • Trigger: On Pull Request to the main branch with changes in the /agents directory.
    • Steps:
      1. Validates the submitted JSON file against the official schema.
      2. Performs an HTTP request to the provided wellKnownURI.
      3. Compares key data between the submitted file and the fetched agent-card.json to verify ownership.
      4. Posts a success or failure status comment on the PR.
  • Workflow 2: Publish (publish.yml)
    • Trigger: On push (merge) to the main branch.
    • Steps:
      1. Consolidate Data: Reads all files in /agents and compiles them into a single registry.json file.
      2. Deploy Website: Deploys the contents of the /docs directory AND the newly generated registry.json to GitHub Pages.
      3. Publish Client: (If changes in /client-python/ are detected) Builds and publishes the package to PyPI.

2.3. The Public Endpoints (Services)

These are the user-facing parts of the registry.

  • Website: https://www.a2aregistry.org
    • A static, searchable website that fetches data from registry.json to provide a human-readable view of the agents.
  • API Endpoint: https://www.a2aregistry.org/registry.json
    • A static JSON file containing the entire agent registry. This is the primary endpoint for all programmatic access.
  • Python Client: pip install a2a-registry-client
    • A lightweight, installable library that simplifies fetching and filtering agents from the registry for Python developers.

3. User Workflows

3.1. Submitting an Agent:

  1. A developer forks the repository.
  2. They create a new file: /agents/my-cool-agent.json.
  3. They submit a Pull Request.
  4. The CI pipeline validates their submission and provides feedback.
  5. A maintainer reviews and merges the PR. The agent is now live.

3.2. Consuming the Registry:

  • Via an Agent/Script: An agent makes an HTTP GET request to https://www.a2aregistry.org/registry.json to get the full list of agents, then filters the data locally.
  • Via the Python Client: A developer runs pip install a2a-registry-client and uses simple functions like registry.find_by_capability("weather-forecast").
  • Via a Web Browser: A user visits https://www.a2aregistry.org to browse and search for agents.

4. Project Roadmap (Milestones)

Phase 1: Minimum Viable Product (MVP)

  • Set up the GitHub repository and file structure.
  • Define and publish the official Agent JSON Schema.
  • Implement the validate-pr.yml GitHub Action.
  • Implement the publish.yml Action to generate and deploy registry.json.
  • Launch a basic placeholder page at www.a2aregistry.org.

Phase 2: Usability & Tooling

  • Develop and publish the first version of a2a-registry-client to PyPI.
  • Build a functional, searchable user interface for the website.
  • Write comprehensive documentation (README.md, CONTRIBUTING.md).

Phase 3: Community Growth

  • Promote the registry to attract the first 20 agent submissions.
  • Establish a clear governance model for project maintainers.
  • Explore advanced features like semantic search or agent health checks.