TL;DR: What is agents.json? In short, it is a machine-readable description of the actions an AI agent can take on a website, built on top of the existing OpenAPI standard and started by a company called Wildcard AI, or that’s the aim.
It is an early-stage proposal at version 0.1.0, not an adopted web standard, and it only matters for sites that expose real actions for agents to perform, such as checkout or booking systems.
If you run a normal brochure or local service website, a missing agents.json file is not a problem, and any tool that flags it as a failure is overstating its importance.
If you have run one of the new “AI readiness” checks on your website lately, there is a fair chance it told you that you are missing an agents.json file, complete with a worrying red cross next to it. Before you panic or reach for your wallet, it is worth understanding what that file is, who is behind it, and whether your business has any reason to care.
The short version is that for most small business websites, you do not need one, and the tool flagging it is doing a little theatre. Here is the longer version, in plain English.
What is agents.json really?
An agents.json file is a small text file, usually placed at the root of a website, that describes how an AI agent can interact with that site’s behind-the-scenes functions. Think of it as a machine-readable instruction manual written specifically for software that acts on your behalf.
The key word there is act. We are not talking about an AI simply reading your page and summarising it. We are talking about an agent doing something: searching a product catalogue, adding an item to a basket, booking an appointment, or submitting a form. The agents.json file tells the agent which of these actions exist, what information each one needs, and how they chain together.
It is built on top of an older, well-established standard called OpenAPI, which developers have used for years to describe how software talks to other software. The new file takes that foundation and reshapes it so that an AI agent, rather than a human developer, can understand and use it.
How it differs from llms.txt and a sitemap
This is where a lot of the confusion comes from, because these things get lumped together in audit results as though they are all the same kind of thing. They are not. Each one does a different job.
- An XML sitemap tells search engines which pages exist on your site so they can be found and indexed. This is genuinely important and has been for years.
- An llms.txt file is a newer proposal that tells AI models which of your content is worth reading and how to make sense of it. It is about understanding. There’s still no agreed standard or protocal
- An agents.json file goes a step further still. It is not about reading or understanding your content, it is about doing things. It is about action.
So you can picture a ladder. A sitemap helps you get found. An llms.txt helps you get understood. An agents.json helps an agent operate your site. The vast majority of small business websites only ever needed the first rung, and most of the value still sits there.
Who made it and how established it really is
This part matters, because it is easy to assume that anything appearing in an audit tool is an industry standard handed down from on high. It is not.
The agents.json specification was started by a company called Wildcard AI, a startup that went through the Y Combinator accelerator. It is an open specification, which means anyone can read it and contribute, but it is a single company’s proposal rather than the output of a recognised standards body like the W3C or the IETF, and it is not something the major AI labs have jointly agreed on.
It is also very new. The current version is 0.1.0, and the project’s own documentation openly describes it as evolving, says it needs community input, and acknowledges there are still open questions, including whether website owners should be doing this at all versus the API providers handling it themselves.
None of this means the idea is bad. Agentic commerce, where AI agents complete tasks for people, may well become significant, and something like agents.json may end up part of that. But “may end up significant” is a very different thing from “your café website is failing because you do not have one today”.
Does your website actually need one?
The honest answer for almost every small business we work with is no, not yet, and possibly not ever in its current form. The deciding question is simple: does your website let a visitor do something through a programmable function, or does it just present information?
Here is how that plays out across the kinds of sites we see most often.
| Type of website | Does it expose actions? | Needs agents.json? |
|---|---|---|
| Brochure or local service site | No, it presents information and a contact form | No |
| Blog or content site | No, it is there to be read | No |
| Online shop with a public API | Yes, search, basket and checkout | Possibly, later |
| Booking or scheduling platform | Yes, availability and booking actions | Possibly, later |
| SaaS product with an open API | Yes, that is the whole point of it | Worth watching closely |
Even in the “possibly, later” cases, there is no rush. The technology is young, adoption is thin, and you would be implementing something that may change shape before it settles. Watching is a perfectly respectable strategy.
Why audit tools flag it as a failure
If agents.json barely applies to your site, why does an audit tool present its absence as a red cross sitting right alongside genuinely important checks like your sitemap and your structured data?
Because it works as a marketing device. Putting a speculative, niche file in the same list as established essentials makes the overall result look more alarming, and an alarmed business owner is more likely to click the “we can help you fix this” button that usually sits at the bottom of the report. It is a nudge, not a neutral diagnosis.
This is not to say the tools are useless. They can surface real issues worth acting on. It just means the results need a human eye to separate the genuine from the manufactured urgency, which is exactly the kind of thing a good web designer should be doing for you rather than letting a scoreboard set your priorities.
Is it a security risk?
This is a sensible question, because “let AI agents perform actions on your site” is the sort of phrase that should make anyone pause.
The file itself is not the risk. An agents.json file only describes functions, it does not create them and it cannot execute anything on its own. Publishing one does not open a door that was not already there. The real question is whether the functions it points to are properly secured in their own right, with the right authentication and rate limiting, just as any web function should be.
A helpful way to picture it: the file is a labelled map to the doors of your building. If your doors are properly locked, a map is harmless. If a door was left unlocked, the map makes it easier to find, but the unlocked door was the problem all along, not the map.
For a brochure site with no action-performing functions, there are no doors for the map to point at, so the question does not even arise. For sites that do expose actions, the right framing flips the audit tool’s scare tactic on its head. The question is not “do you have an agents.json file?” but “are the functions on my site properly secured?”, and that has been the right question all along, with or without any of this.
What to do right now
If you have just been told your site is missing an agents.json file, here is a calm, sensible order of priorities.
- Confirm whether your website actually exposes any programmable actions. For most small business sites the answer is no, and you can stop worrying here.
- Make sure the things that genuinely matter are in good shape first: a working XML sitemap, solid structured data, fast loading, and content that answers real questions.
- If you do run a shop, booking system, or SaaS product, treat agents.json as something to watch rather than rush, and make sure the underlying functions are properly secured regardless.
- Be sceptical of any audit that presents a version 0.1.0 proposal as a failed essential. Ask what each flagged item actually does for your business before acting on it.
The thread running through all of this is the same one we come back to again and again: chase the things that move the needle for real people and real customers, and do not let an automated scoreboard, or the company selling the fix, decide your priorities for you.
If you would like a second opinion on what your AI readiness report is actually telling you, that is the sort of thing we are always happy to look at. You can find more plain-English explainers like this one in our knowledge base, including What is LLMs.txt and how to get cited by AI & LLMs.
Sources
If you’d like an honest, no commitment conversation about AI & LLMs, and how your business might be able to grow using them.
