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.
