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

The card is at the old path

A2A moved the card to /.well-known/agent-card.json in v0.3.0, and that is the path registered with IANA. A card at /.well-known/agent.json is found by this audit and not by a current client, which looks only at the registered one.

Serve it at the new path. Keep the old one as a redirect, or as a second copy, if anything already depends on it.

A card shape from neither generation

A 1.0 card declares supportedInterfaces[]. A 0.3 card declares a top-level url and protocolVersion. Yours has neither, so there is no ruleset to validate it against.

Usually a hand-written card that predates both, or one built from a blog post. Rebuild it against the current specification.

supportedInterfaces is empty

The array exists and lists nothing, so the card describes an agent with no address. Declare at least one:

"supportedInterfaces": [
  { "url": "https://example.com/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
]

An interface missing a field

Every entry needs all three: url, protocolBinding and protocolVersion. Together they say where to connect and how to speak, and a client cannot infer either from the other.

An unrecognised protocolBinding

A2A 1.0 defines three: JSONRPC, GRPC and HTTP+JSON. Anything else is skipped, and an interface that is skipped is an interface that is not there.

The card uses authentication

Removed from the specification and replaced by securitySchemes, which carries the same information in the OpenAPI vocabulary clients already parse.

If your agent is open, the right move is to declare nothing. An empty authentication object says something about authentication rather than nothing, which is why the field went.