Skip to content

docs: clarify terminology, scope, and architecture model in README#8

Open
mindpower wants to merge 2 commits intoAgent-Card:mainfrom
mindpower:jbu/readme
Open

docs: clarify terminology, scope, and architecture model in README#8
mindpower wants to merge 2 commits intoAgent-Card:mainfrom
mindpower:jbu/readme

Conversation

@mindpower
Copy link
Collaborator

@mindpower mindpower commented Dec 4, 2025

Summary

This PR updates the README to resolve ambiguity regarding the definitions of "Agent" vs. "Server" and explicitly defines the distinct scopes of the AICard and AICatalog specifications. It introduces the term "AI Service" as the standard logical entity and renames the protocol map to "Interfaces" to avoid naming collisions.

Motivation

Recent discussions (e.g., #6, #4 (comment), #4 (comment)) highlighted that:

  1. The term "Agent" is too narrow for MCP tool servers, while "Server" is too ambiguous (confusing Host vs. Entity).
  2. Using services inside the Card to list protocols created a naming collision if we ever wanted to refer to the top-level entity as a "Service."

Key Changes

  1. New Terminology Hierarchy:
    • Host: The infrastructure/domain.
    • AI Service: The logical entity (covers both autonomous Agents and passive Tools).
    • Protocol Interface: The specific endpoint (A2A/MCP) exposed by the Service.
  2. Scope Clarification:
    • AICard: Defined as the Identity & Capability definition (The "Digital Passport").
    • AICatalog: Defined as the Host Inventory (The "Building Directory").
  3. Schema Alignment:
    • Renamed the protocol map in the Card description from services to interfaces to align with A2A's supportedInterfaces and prevent naming conflicts.
  4. Discovery Patterns:
    • Clarified support for both Decentralized (.well-known) and Centralized (Registry API) discovery.

Impact

These changes align the documentation with the consensus reached in the schema discussions in V1 schema proposal PR, providing a clearer mental model for implementers integrating both A2A and MCP protocols.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant