Understanding agents.json: an experimental approach to describing agent interactions

AI applications can read websites and, with suitable tools and permission, perform actions. That creates a practical need to describe interfaces clearly. Files called agents.json appear in proposals for making API workflows easier for compatible agents to discover and use. They should not be presented as a universally adopted web standard or a prerequisite for being found by AI search.

Before implementing a manifest, identify the actual client or integration that will consume it. Support, syntax and discovery rules depend on the chosen specification. Merely placing an arbitrary JSON file on a website does not give Apple, Google or other assistants a working connection to the business.

How does this differ from robots.txt?

Robots.txt provides crawl directives for cooperating crawlers. It is not authentication, does not grant access rights and is not a reliable way to keep a URL out of search results. An agent manifest describes a different concern: the interfaces or workflows a compatible client may use.

• Robots.txt: communicates crawling rules to clients that observe them.
• An agent manifest: may describe operations, endpoints and their expected inputs under a particular proposal.

Neither file grants permission to write to a database. The server must enforce access independently. Missing an agents.json file does not establish that assistants will ignore the website or send visitors to a competitor.

Choose a specification before choosing the syntax

One open proposal, maintained by Wildcard, describes API and agent interaction contracts built on OpenAPI. Other projects use related names for different ideas. Read the chosen specification and check that the intended consumer supports it before deciding where the file belongs or which fields to include.

Valid JSON is only the first check. A file can parse correctly while failing the relevant schema or describing an operation that does not exist. Version the manifest alongside the application and document how consumers are expected to discover it.

Describe endpoints and their behaviour

An API endpoint needs a method, input format, response format and documented error behaviour. For state-changing operations, it also needs authentication, authorisation and safeguards against unintended repetition. A description helps a client form a request; it does not establish that the request should be accepted.

The following is an illustrative internal description, not a conforming example of a universal agents.json specification:

{
  "documentation": "https://example.com/api/docs",
  "operations": [
    {
      "name": "request_quote",
      "endpoint": "/api/quote-requests",
      "method": "POST",
      "requires_confirmation": true
    }
  ]
}

Implement the real API and its controls separately. Do not copy this sketch into production and assume an assistant will discover or obey it. A technical SEO audit can examine a public website, but it cannot certify an agent transaction system.

Permissions and scope belong on the server

Define the operations each authenticated user or client is allowed to perform. Restrict data access to the correct organisation and records, validate inputs and require appropriate confirmation for consequential actions. A public manifest may describe these requirements but cannot enforce them.

For a first integration, prefer limited, reversible operations and a clear approval process. Treat text supplied by users, external pages and tool responses as untrusted. Personal data handling requires a separate assessment of the actual processing and contracts; a manifest is not a compliance mechanism.

Client identity and abuse prevention

A user-agent string alone does not prove who is making a request. Where a provider publishes a verification method, follow its current documentation for the specific crawler or client. Do not assume every AI request has a verifiable signature or a stable published IP range.

Use appropriate authentication for application actions, along with rate limits, monitoring and request validation. Keep credentials out of public files. Log enough to investigate failures and misuse without unnecessarily storing sensitive payloads.

Generating a manifest from an application

A framework such as Laravel can generate a machine-readable description from maintained application configuration. That can reduce drift when the same operation appears in documentation and an integration manifest. It is an implementation choice, not a requirement for compatibility.

Only expose operations that are intended for the relevant audience. Do not automatically publish every internal route or capability. A newly generated file will not necessarily be fetched immediately, so versioning and compatibility remain important even when generation is automatic.

A five-step implementation checklist

1. Define the use case: select a specific client and a workflow worth supporting.
2. Choose and validate the format: follow the supported specification and document the interface.
3. Implement server controls: authentication, authorisation, input checks and confirmation requirements.
4. Test in isolation: include invalid input, denied access, duplicate requests and unavailable dependencies.
5. Release and monitor: track real usage, errors and compatibility before widening access.

Set response-time targets based on the integration's requirements. There is no universal millisecond deadline for every agent. Use clear timeouts and recovery behaviour rather than assuming requests always succeed quickly.

What value might an integration provide?

A supported interface can reduce manual work in a defined process. For example, an authorised assistant might prepare a quote request or retrieve permitted order information. The benefit comes from a working integration and the task it supports, not from the filename itself.

• Fewer manual steps in a measured workflow.
• Clearer contracts between an API provider and its clients.
• More consistent validation and error handling when the integration is well designed.

There is no established basis here for promising increased domain reputation, organic traffic or conversion solely from publishing agents.json. Test whether the proposed consumer uses it and whether that usage provides value.

Keep experimentation separate from search fundamentals

Agent interfaces may become useful in selected B2B processes. That does not mean all business interactions are moving to autonomous negotiation or that ordinary SEO is obsolete. Public content still needs to be useful, accessible and accurate.

Google's guidance for its AI search features does not require special machine-readable AI files. Treat agent manifests as integration experiments with explicit consumers and controls. Contact devBoys if you have a concrete workflow to assess; we can help separate the useful engineering work from unsupported visibility claims.