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

> An agent card is the JSON document an A2A (Agent2Agent) client reads first: who the agent is, where to reach it, how to authenticate and which skills it offers. Publish one if you run an agent that other agents should call.

Checked 2026-09-30 against Agent-Readiness Grade 1.3.0. HTML version: https://grade.agentexchange.work/fix/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).

## Why it matters for AI agents and crawlers

The [A2A specification, version 1.0.0](https://a2a-protocol.org/latest/specification/) 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](https://a2a-protocol.org/v0.2.6/specification/) 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](https://grade.agentexchange.work/tools/agent-card-generator) builds this from a form and flags missing required fields.

agent-card.json (A2A 1.0):

```json
{
  "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):

```yaml
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:

```js
// 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": "*",
    },
  });
}
```

## How to verify

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

```sh
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.

Re-grade: https://grade.agentexchange.work/grade?url=example.com&fresh=1

## 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

- [Agent2Agent (A2A) Protocol Specification, version 1.0.0](https://a2a-protocol.org/latest/specification/) (A2A Protocol)
- [A2A Protocol Specification, version 0.2.6 (agent card at /.well-known/agent.json)](https://a2a-protocol.org/v0.2.6/specification/) (A2A Protocol)

## Related

- [openapi.json](https://grade.agentexchange.work/fix/openapi-json.md): Your API described at /openapi.json; one of four files for the agent-surface point.
- [MCP endpoint and census](https://grade.agentexchange.work/fix/mcp-endpoint.md): An MCP endpoint at /mcp, and a listing among hosts that sell to agents through x402.
- [x402 manifest](https://grade.agentexchange.work/fix/x402-manifest.md): A JSON list of your x402 paid routes at /.well-known/x402; only if you sell per request.
- [A2A agent card generator](https://grade.agentexchange.work/tools/agent-card-generator)
- [All fix guides](https://grade.agentexchange.work/fix)