SEO

Agent Card

Also called agent-card.json, .well-known agent card

A proposed JSON file at a fixed address telling software agents what a business does and what they may do.

Quick facts: Agent Card

Category
SEO
Also called
agent-card.json, .well-known agent card
Level
Advanced
Affects
Machine discovery of your services, agent traffic, data consistency
Where to see it
Your hosting file manager, a JSON validator, server logs
In this article4
  1. How an agent card works
  2. Why agent cards matter
  3. Where agent cards go wrong
  4. What to do about it

How an agent card works

An agent card is a JSON file published at a fixed address — /.well-known/agent-card.json — that describes an organisation in machine-readable terms: who it is, what it offers, what an agent is permitted to do with it, and where that action can be carried out. The .well-known directory is a long-established convention for files software looks for without being linked to them, which is why the proposal chose it.

The idea comes out of agent-to-agent protocol work, where one piece of software has to discover another’s capabilities before it can use them. Applied to an ordinary business website, it is an attempt to give an agent one stable place to read the facts instead of scraping them out of a page written to persuade a person. It sits alongside other proposals of the same era, such as llms.txt.

Why agent cards matter

The problem it addresses is real. Today an agent has to infer your services, your coverage area and your booking route from marketing prose, and inference is where wrong answers come from. Anything that states those facts explicitly removes guesswork, which is the same argument that has always made structured data worth the effort.

Be careful about the weight you put on it, though. Adoption is early, the shape of the file is not fixed, and no major search engine or assistant has published a commitment to read one. It is a proposal being tried in public, not a channel with results attached.

Where agent cards go wrong

The main risk is drift. A file that repeats facts held elsewhere on your site — services, hours, contact routes — becomes wrong the moment one of them changes and nobody remembers the file exists. A confidently wrong machine-readable statement is worse than none at all, because it is the version software trusts.

The second risk is over-promising. Declaring that agents may book, order or transact tells software to try, and if the process behind it needs a human step somewhere, the attempt fails in front of a customer. Declare only what works from end to end without you.

The third is buying it as a product. Nobody can currently promise a ranking, a citation or an enquiry from publishing one, so a proposal that prices it as an outcome is not being straight with you.

What to do about it

If you want to experiment, keep it small and keep it true. Publish only facts that already appear on the site, generate the file from the same source as the pages rather than typing everything twice, and give it a review date. Check it after every change to your services, hours or contact details.

If you would rather wait, you lose nothing. The dependable version of this work is structured data inside the pages themselves, plus a site that answers plainly in text. Both are read today, by engines that document what they do with them.

Do and do not

Do

  • Generate the file from the same source as your pages
  • Declare only actions that work without a human step
  • Set a review date and check it after changes

Do not

  • Pay for it as a promised ranking outcome
  • Repeat facts you will forget to update
  • Publish it behind a login or a redirect

Questions people ask about this

Where exactly does the agent card file go?

At the root of your domain, inside the .well-known directory, so the address ends in /.well-known/agent-card.json. That folder is a long-standing convention for files software looks for without being linked to them. It has to be served as JSON and be reachable without a login or a redirect, otherwise an agent records a failure and moves on.

Will publishing an agent card improve my rankings?

There is no evidence that it will. No major search engine has said it reads the file, and none lists it among ranking or retrieval inputs. Publish it because you want to describe your business to software accurately, not because you expect a position to move. Ranking work still belongs with content, links and technical health.

Is an agent card the same as structured data?

No. Structured data is embedded in each page, describes that page, and the major engines document what they do with it. An agent card is one separate file describing the whole organisation and what agents may do with it, and it remains a proposal. The two can coexist, but only one of them is read at scale today.

Related terms

Found this useful?

Share it, or ask an AI to summarise it

Back to the glossary

Knowing the term is the easy part

Applying it to your own site and budget is the work. Book a call and I will tell you what actually applies to you.