AxonariBuild · Automate
Reference · updated 2026-09-16

What is agent-card.json, and do you need one?

agent-card.json is a JSON document published at /.well-known/agent-card.json that describes an agent or a service to other agents: its identity, its capabilities, its declared skills, and how to reach it. It comes from the A2A (Agent2Agent) protocol, and it is how an arriving agent learns what you can do without having to infer it from your marketing pages.

What problem it solves

An agent landing on your site can read your words. What it cannot do is work out which of your capabilities it may invoke, what parameters they take, or whether it should be calling you at all for the task in hand. The agent card answers those questions in a format designed to be parsed.

The useful mental model is a service directory entry rather than an API specification. It says what exists and when to use it; the API docs say how.

What to put in it

Identity first: name, description, provider, a documentation URL. Then the skills, and this is where most cards are weak. A skill needs an id, a name, a description that says when to use it, and examples written the way a user would phrase the request.

Write the descriptions for the agent, not for a human browsing a catalogue. 'Submit a project enquiry on behalf of a user who has explicitly asked to get in touch' is a better description than 'Contact form', because it tells the agent when not to fire.

How it relates to everything else

The agent card, llms.txt and a resource catalog overlap and that is fine. llms.txt describes the business in prose. The resource catalog enumerates machine-readable resources. The agent card declares callable capabilities. An agent may arrive through any of them, so keeping the three consistent matters more than keeping them distinct.

We generate all three from one module for exactly this reason. Three hand-maintained files drift within a month.

A minimal agent card with one well-described skill
{
  "protocolVersion": "0.3.0",
  "name": "Acme Ltd",
  "description": "Commercial refrigeration, UK and Ireland.",
  "url": "https://acme.example",
  "provider": { "organization": "Acme Ltd", "url": "https://acme.example" },
  "version": "1.0.0",
  "capabilities": { "streaming": false },
  "skills": [
    {
      "id": "request-survey",
      "name": "Request a site survey",
      "description": "Book a refrigeration survey for a commercial kitchen. Only call when the user has asked to arrange one.",
      "tags": ["survey", "booking", "refrigeration"],
      "examples": ["Book a refrigeration survey for a restaurant in Leeds."]
    }
  ]
}

Does your site have this?

The free checker scores your site against agent-card.json and everything else on this list, out of 100, in about ten seconds. It names what is missing rather than handing you a number.

Run the free check→

Common questions

Where does agent-card.json go?
At /.well-known/agent-card.json, served as application/json. It is a well-known URI, so the path is part of the contract and should not be moved.
Do I need an agent card if I have no API?
It still helps. Even with no callable endpoints, the card states your identity and what you do in a machine-readable form, and it is the file an A2A-aware agent looks for first. Declare no skills rather than inventing them.

Sources

  1. 01A2A Protocol, a2a-protocol.org

The rest of the reference