Fix agent card: publish /.well-known/agent-card.json

What the grade checks

• GET https://example.com/.well-known/agent-card.json with a 7-second timeout. It counts when the answer is HTTP 200 and parses as a JSON object; the evidence line shows the agent's name. An HTML page from a catch-all route does not count.
• The grade checks presence, not the schema. A2A clients do check the schema, so use the required fields below.
• Any one of agent-card.json, openapi.json, mcp-registry-auth or /.well-known/x402 earns the agent-surface point (the area is capped at 2).

The agent-surface point of the machine-readable surfaces area (shared with three other files). The full scoring rules are on the methodology page.

Why it matters for AI agents and crawlers

The A2A specification, version 1.0.0 says A2A servers MUST make an agent card available and gives https://{server_domain}/.well-known/agent-card.json as the discovery location (section 8.2), registered as a well-known URI (section 14.3).

Required fields in 1.0 (section 4.4.1): name, description, supportedInterfaces (each with url, protocolBinding and protocolVersion), version, capabilities, defaultInputModes, defaultOutputModes and skills (each with id, name, description and tags). Version 1.0 has no top-level url: endpoints are listed in supportedInterfaces, first one preferred. The extended-card flag moved into capabilities.extendedAgentCard.

The spec asks servers to send Cache-Control and an ETag with the card (section 8.6) and says the card should not contain credentials. Earlier versions used a different path: version 0.2.6 put the card at /.well-known/agent.json.

How to fix it

1. Write the card

   Describe the agent, the endpoint clients should call and at least one skill. The agent card generator builds this from a form and flags missing required fields.

   agent-card.json (A2A 1.0)

   {
     "name": "Example Support Agent",
     "description": "Answers questions about Example Co invoices and account status.",
     "supportedInterfaces": [
       { "url": "https://example.com/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
     ],
     "provider": { "organization": "Example Co", "url": "https://example.com" },
     "version": "1.0.0",
     "documentationUrl": "https://example.com/docs/agent",
     "capabilities": { "streaming": false, "pushNotifications": false },
     "defaultInputModes": ["text/plain"],
     "defaultOutputModes": ["text/plain", "application/json"],
     "skills": [
       {
         "id": "invoice-status",
         "name": "Invoice status",
         "description": "Looks up the status of an invoice by its number.",
         "tags": ["invoices", "billing"],
         "examples": ["What is the status of invoice INV-1042?"]
       }
     ]
   }

2. Host it at /.well-known/agent-card.json

   The .json extension gets you application/json on almost every host; the usual trap is a host that skips folders starting with a dot.

   Static site

   Create a .well-known folder in the web root and save the file inside it as agent-card.json. Jekyll-based hosts skip dot-folders unless _config.yml includes them.

   _config.yml (Jekyll only)

   include: [".well-known"]

   WordPress

   Upload .well-known/agent-card.json to the WordPress root folder by SFTP or your host's file manager. Many hosts already have a .well-known folder for certificate checks; the file can live next to it.

   Next.js

   Save it as public/.well-known/agent-card.json. Files in public/ are served from the site root with a content type taken from the extension.

   Cloudflare

   Deploy .well-known/agent-card.json with your static assets, or answer the path from the Worker with a cache header:

   Cloudflare Worker

   // CARD is the agent card object from step 1
   if (url.pathname === "/.well-known/agent-card.json") {
     return new Response(JSON.stringify(CARD), {
       headers: {
         "content-type": "application/json",
         "cache-control": "public, max-age=3600",
         "access-control-allow-origin": "*",
       },
     });
   }

Free generator: A2A agent card generator. Builds an A2A 1.0 agent card with required fields checked.

How to verify

Check the status and content type, then that the required fields are there.

shell

curl -s -o /dev/null -w "%{http_code} %{content_type}\n" https://example.com/.well-known/agent-card.json
curl -s https://example.com/.well-known/agent-card.json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const c=JSON.parse(s);console.log(c.name,"|",(c.supportedInterfaces||[])[0],"|",(c.skills||[]).length,"skills")})'

200 application/json, then the agent's name, its first interface and a skill count. An HTML content type means a catch-all route answered.

Then re-grade your site: the result lists the evidence for this check.

Questions

Do I need an agent card if I don't run an agent?

No. The card describes an A2A agent. A site without one loses nothing real, and openapi.json, mcp-registry-auth or /.well-known/x402 earn the same point.

Should I also serve /.well-known/agent.json?

A2A 0.2.6 used /.well-known/agent.json; 0.3.0 and 1.0 use /.well-known/agent-card.json, the path this check reads. Serving the same card at both paths is harmless for older clients.

How do I declare authentication?

Add securitySchemes, where each entry holds exactly one of apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme or mtlsSecurityScheme, and list what a client needs in securityRequirements. The generator writes these for an API key, HTTP bearer, OAuth 2.0 and OpenID Connect.

Which protocolBinding values are valid?

The core bindings are JSONRPC, GRPC and HTTP+JSON. The field is an open string, so other bindings can be named.

Sources

Primary documentation, read 2026-09-30. Vendors change these pages; follow the link before relying on a detail.

• Agent2Agent (A2A) Protocol Specification, version 1.0.0 (A2A Protocol)
• A2A Protocol Specification, version 0.2.6 (agent card at /.well-known/agent.json) (A2A Protocol)

Related

• openapi.json: Your API described at /openapi.json; one of four files for the agent-surface point.
• MCP endpoint and census: An MCP endpoint at /mcp, and a listing among hosts that sell to agents through x402.
• x402 manifest: A JSON list of your x402 paid routes at /.well-known/x402; only if you sell per request.
• Generator: A2A agent card generator
• All fix guides · All generators · Graded sites · How the grade works