Proposal: agent.json format for universal agent manifests

[HOTAgithub]

Overview

I'd like to propose an agent.json format — a universal, machine-readable manifest for describing AI agents across registries. This is the agent-level equivalent of server.json, designed as a superset that's complementary to both server.json and the proposed skills.json (#895).

Live spec: https://github.com/HOTAgithub/agent-json
Working prototype: https://agent-router.pickaxe.workers.dev/

Problem Statement

• As of May 2026, 104,000+ AI agents are spread across 15+ registries (Smithery, MCP Registry, Glama, HuggingFace, Aiia.ro, etc.)
• Each registry uses a different metadata schema (server.json, smithery.yaml, glama.json, A2A Agent Card, etc.)
• There's no universal format to describe agents (as opposed to just servers or skills)
• Cross-registry discovery is impossible without manual normalization

Proposed Format

Minimal agent.json (2 required fields only):

{
  "name": "my-agent",
  "description": "A helpful agent that does X",
  "version": "1.0.0",
  "protocol": ["mcp", "a2a"],
  "capabilities": ["text-generation", "tool-use"],
  "endpoint": "https://example.com/agent",
  "auth": { "type": "bearer" },
  "trust": {
    "score": 0.85,
    "source": "agent-quality-graph"
  }
}

Well-known URI convention: /.well-known/agent.json

Design Principles

• Only 2 required fields (name, description) — maximum adoption, minimum friction
• Superset, not replacement — maps to/from server.json, skills.json, A2A Agent Card, glama.json
• Protocol-agnostic — supports MCP, A2A, HTTP, gRPC
• Trust-native — optional trust field for quality/reputation scores (see IETF Draft below)
• Reverse-DNS namespace — compatible with existing MCP Registry naming conventions

Why Extend This Registry?

• The MCP Registry already has the infrastructure for discovery, namespacing, and auth
• server.json describes MCP servers; skills.json describes skills; agent.json would describe the agent itself — its identity, capabilities, and trustworthiness
• Together these three manifests provide a complete picture: what the server offers, what skills it has, and who the agent is

Related Work

• IETF Draft: draft-hori-agent-quality-graph — standardized trust scoring for agents via delegation graphs
• W3C AIVS: Proposed integration with Agent Identity Verification Specification
• Agent Router API: Working prototype searching Smithery + MCP Registry + Glama in parallel using agent.json format

I'm gauging interest before sharing the full JSON Schema and detailed mapping tables. Would this be a welcome addition to the registry ecosystem?