What an agent card is, and what goes in one

The short version

An agent card is a public description of an agent, written for other software to read. It says what the agent is called, what it does, which skills it offers, how to reach it, and what authentication it needs. Other agents read it before they send a single request.

Under the A2A protocol the card lives at a fixed address on your domain: /.well-known/agent-card.json. The /.well-known/ folder is the internet's standard place for files that software looks for automatically, the same idea as robots.txt.

What the current version requires

In A2A 1.0 a card must include a name, a description, a version, the agent's capabilities, its default input and output formats, a list of skills, and at least one supported interface. The interface is where the endpoint lives: a URL, the protocol binding it speaks (JSON-RPC, gRPC, or HTTP with JSON), and the protocol version.

Earlier versions put the endpoint URL and protocol version at the top level of the card. If you are reading an older tutorial, that is the most visible difference.

{
  "name": "Riverside Dental",
  "description": "Answers questions about services and requests appointments.",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://example.com/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "provider": { "organization": "Riverside Dental", "url": "https://example.com" },
  "capabilities": { "streaming": false, "pushNotifications": false },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["application/json", "text/plain"],
  "skills": [
    {
      "id": "request_appointment",
      "name": "Request an appointment",
      "description": "Proposes a time. A person at the practice confirms it.",
      "tags": ["booking", "appointments"]
    }
  ]
}

Describe skills the way a customer would ask

Each skill has an id, a name, a description, and tags, and can carry example requests. Write the description for a reader who has never heard of your business: what the skill does, what it needs, and what it will not do. "Proposes a time; a person confirms it" is more useful to another agent than "Booking."

Keep the list short and true. A card that advertises a skill your endpoint cannot perform is worse than a card with one honest skill.

Build one without writing JSON by hand

The agent card builder on this site produces a valid 1.0 card from a short form, runs entirely in your browser, and tells you exactly where to publish the file.