What agents.json describes
Sources checked 2026-09-15
agents.json is one pattern for describing actions and endpoints for automated clients. Treat it as a specific declaration format, not as a universal requirement for an agent usable site.
The specification has stayed at version 0.1.0 since early 2025, and adoption since then has shifted toward MCP and newer discovery surfaces. A site can adopt agents.json, but it should not be treated as the settled or required way to declare an action surface. Where llms.txt tells an agent what a site contains, agents.json describes the actions and endpoints an agent is allowed to use, so an automated client can move from reading to doing without a human wiring it up first.
Purpose
The file lists the operations a site exposes to agents, often pointing at an OpenAPI description or specific endpoints, along with the authentication a client needs to call them. A client reads the file, learns which actions exist, and calls them within the rules the site sets. Most sites expose actions only through a human interface, a form or a checkout flow that a person clicks through, and a client cannot reliably reverse-engineer that interface. A declared action surface removes that guesswork.
Example
A minimal agents.json entry names an action, such as checking an order status, and points to the endpoint and method that perform it, together with the authentication scheme the endpoint expects. The file describes the shape of the call. It does not perform any authorisation itself and does not replace the checks the endpoint runs when the call actually arrives.
Alternatives
agents.json sits beside other declarations a client looks for. An MCP server card describes a site's MCP server and its tools, an API catalog lists endpoints directly, and OAuth discovery describes how to authenticate. A site that has already published an MCP server exposing the same actions may not need a separate agents.json file, since the live tools list serves the same purpose and cannot go stale the way a static file can.
Limits
Declaring an action in agents.json describes what exists. It does not grant a client permission to call it, and it does not perform the authorisation or rate limiting that has to happen on the server when the call arrives. Those checks live at the endpoint, not in the declaration file, and a site still has to enforce them regardless of what agents.json says. Treat the file as documentation a client can parse, not as an access control mechanism.
Frequently asked
What is agents.json?
agents.json is a machine-readable file that declares what an AI agent can do on a site and how, describing the actions and endpoints an agent is allowed to use, often pointing at an OpenAPI description, along with the authentication a client needs. The specification has stayed at version 0.1.0 since early 2025.
How is agents.json different from llms.txt?
llms.txt tells an agent what the site contains. agents.json describes the actions an agent can take, so a site moves from something an agent can read to something an agent can operate, though the authorisation for any given call still happens at the endpoint.
Does agents.json replace llms.txt?
No. llms.txt tells an agent what the site contains and agents.json describes the actions an agent can take. Together they describe both what a site holds and what a client may do with it, though neither one performs the server side checks a call still needs.