What is agents.json?

1.What problem does agents.json address?

OpenAPI describes individual endpoints well, but it was written for human developers. An agent reading an OpenAPI file sees hundreds of operations and has to guess which ones to call, in which order, to reach an outcome such as 'create an invoice and email it'. agents.json keeps OpenAPI as the base and adds a layer that states those sequences explicitly.

2.What are flows and links?

• Flow: a named sequence of one or more API calls that reaches a specific outcome.
• Link: a connection between actions, describing how data from one call is passed to the next.

Because flows are declared by the API owner, an agent can pick a flow by its outcome instead of planning the call sequence itself.

3.Where does the file go?

The specification proposes /.well-known/agents.json so agents can find it at a predictable path.

GET /.well-known/agents.json HTTP/1.1
Host: api.example.com
Accept: application/json

For the file's schema, use the specification repository; it is changing and we do not reproduce it here.

4.What does agents.json not do?

• It does not replace OpenAPI; it references it.
• It does not run anything. An agent still needs a client that executes the calls, with authentication.
• It is not the same as A2A's Agent Card, which describes an agent, not an API. See A2A.

5.How do you check it?

1. Request /.well-known/agents.json and confirm it returns JSON.
2. Confirm each flow references operations that exist in your current OpenAPI file.
3. Walk one flow by hand with real credentials to confirm the sequence still works after API changes.

6.Where does it sit in the readiness stack?

Layer 3, Act: it is for sites whose tasks run through an API.

Frequently asked questions