Agent Card (A2A)

agent.json not found

Create a /.well-known/agent.json file. In Next.js, place it at public/.well-known/agent.json:

{
  "protocolVersion": "0.2.0",
  "name": "Your Site Name",
  "description": "What your site does and what AI agents can find here.",
  "url": "https://your-site.com",
  "version": "1.0.0",
  "provider": {
    "organization": "Your Company",
    "url": "https://your-site.com"
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["application/json", "text/plain"],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "authentication": {
    "schemes": ["none"]
  },
  "skills": [
    {
      "id": "main-feature",
      "name": "Your Main Feature",
      "description": "What this skill does.",
      "tags": ["feature", "category"],
      "examples": ["Example query 1", "Example query 2"]
    }
  ],
  "documentationUrl": "https://your-site.com/.well-known/openapi.json"
}

Wrong Content-Type

Serve /.well-known/agent.json with Content-Type: application/json. Some agents discard responses with the wrong MIME type before parsing.

# Nginx
location = /.well-known/agent.json {
  default_type application/json;
}

# Express / custom server
res.setHeader('Content-Type', 'application/json; charset=utf-8');

Invalid JSON

Your agent.json file exists but contains invalid JSON. Validate it with a JSON linter or JSON.parse() in your browser console.

Required field missing

The A2A protocol requires these fields: name, description, and url. Add any that are missing to the root of your agent.json.

url points to a different origin

The url field in your agent.json points to a different host than the audited site. Set it to the canonical origin of the site that hosts the agent card:

{
  "url": "https://your-site.com",
  "...": "..."
}

If the agent card describes a service hosted on a different subdomain, that subdomain should serve its own /.well-known/agent.json.

url is not absolute

Use a fully qualified URL (https://...) for the url field. Relative paths or hostnames without scheme are ambiguous when the agent card is fetched outside the original page context.

Empty skills array

Your agent.json has a skills array but it's empty. Add at least one skill describing what your site or agent can do:

"skills": [
  {
    "id": "data-lookup",
    "name": "Data Lookup",
    "description": "Look up specific information from our database.",
    "tags": ["data", "search"],
    "examples": ["Find user by email", "Search products"]
  }
]

Skills missing id or description

Every entry in the skills array needs both an id (so agents can address the skill programmatically) and a description (so they can decide whether to invoke it).

"skills": [
  {
    "id": "search-products",
    "name": "Search products",
    "description": "Search the catalog by name, category, or SKU and return matches with price and availability."
  }
]

No protocol version

Add "protocolVersion": "0.2.0" to declare which version of the A2A protocol your agent card follows. This helps AI agents parse your card correctly.

Missing optional fields

The A2A protocol defines optional fields that improve discoverability:

• capabilities — what protocols you support (streaming, push notifications)
• authentication — auth requirements (none, API key, OAuth)
• documentationUrl — link to your OpenAPI spec or API docs