What agents.json describes
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 a site offers to agents, 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. In the 0.1.0 schema each source points to an OpenAPI description and each action names an operation in it, and the authentication a client needs comes from that description. 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 operation in an OpenAPI description that performs it. The endpoint and method, and the authentication scheme the endpoint expects, come from that description. 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, 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 from the running server rather than from a separate static file.
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. For an audit of whether a site's endpoints enforce what its declared actions promise, contact info@turva.dev.
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 a site offers to agents, each action pointing at an operation in an OpenAPI description that also carries 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.