Specification

A2A Registry agents.json Spec

The multi-agent manifest format for websites hosting multiple AI agents.

Overview

The A2A Registry /.well-known/agents.json format extends the standard A2A Agent Card to support multiple agents on a single domain.

Key Difference

While agent-card.json contains a single agent object,agents.json contains an array of agent objects. This allows platforms, marketplaces, and multi-service websites to expose all their agents in one manifest.

When to Use agents.json

✓ Use agents.json when:

• Your domain hosts multiple distinct services
• You're building a platform with many agents
• Different teams own different agents
• You want one manifest for all capabilities

→ Use agent-card.json when:

• You have a single-purpose service
• Your domain represents one agent
• You want A2A standard compatibility
• Simplicity is preferred

Schema Definition

Field	Type	Required	Description
name	string	✓	Human-readable name of the agent
description	string	✓	What this agent does (used for semantic search)
url	string (URL)	✓	Base URL for the agent's API
version	string	✓	Semantic version (e.g., "1.0.0")
capabilities	array	✓	List of actions the agent can perform
authentication	object		Auth requirements (api_key, oauth, none)
openapi_url	string (URL)		Link to full OpenAPI spec
logo_url	string (URL)		Agent logo/icon image

Single Agent (agent-card.json)

For reference, here's the standard single-agent format at /.well-known/agent-card.json:

{
  "name": "Weather Service",
  "description": "Get real-time weather data for any location worldwide",
  "url": "https://api.weather.example.com",
  "version": "1.0.0",
  "capabilities": [
    {
      "name": "get_current_weather",
      "description": "Get current weather conditions for a city",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name" },
          "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
        },
        "required": ["city"]
      }
    }
  ],
  "authentication": {
    "type": "api_key",
    "header": "X-API-Key"
  }
}

Multiple Agents (agents.json)

The A2A Registry format at /.well-known/agents.json wraps multiple agents in an array:

[
  {
    "name": "Weather Service",
    "description": "Get real-time weather data for any location",
    "url": "https://api.example.com/weather",
    "version": "1.0.0",
    "capabilities": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city"
      }
    ]
  },
  {
    "name": "News Service",
    "description": "Get latest news headlines and articles",
    "url": "https://api.example.com/news",
    "version": "1.0.0",
    "capabilities": [
      {
        "name": "get_headlines",
        "description": "Get top news headlines"
      },
      {
        "name": "search_articles",
        "description": "Search news articles by keyword"
      }
    ]
  },
  {
    "name": "Stock Tracker",
    "description": "Real-time stock prices and market data",
    "url": "https://api.example.com/stocks",
    "version": "1.0.0",
    "capabilities": [
      {
        "name": "get_price",
        "description": "Get current stock price by symbol"
      }
    ]
  }
]

Capability Schema

Each capability describes an action the agent can perform:

Field	Type	Description
name	string	Function name (snake_case recommended)
description	string	What this capability does
input_schema	JSON Schema	Parameters the capability accepts
output_schema	JSON Schema	Response format (optional)

Ready to Register Your Agents?

Submit your domain and we'll automatically detect and index all your agents.

Submit Your Domain Back to A2A Guide