Last week I documented how I implemented agent-permissions.json on this blog. That file answers the question what can an agent do here. But it doesn't answer the question how to do it.

An agent knows it has permission to use my llms.txt generator. But how does it discover the endpoint? What parameters does it need? What format does it receive the response in? What happens if there's an error?

agents.json is an open specification, built on OpenAPI, that answers exactly those questions. It's a formal contract describing how an AI agent can interact with a website's services. It's not a replacement for agent-permissions.json. It's its natural complement.

What agents.json is

agents.json is a specification created by Wildcard AI that extends OpenAPI to describe interaction contracts between APIs and AI agents. The fundamental difference with a standard OpenAPI spec is that agents.json is designed to be consumed by LLMs, not human developers.

What I implemented for my llms.txt generator

My llms.txt generator is a client-side tool. It doesn't have a traditional REST API. But the agents.json concept can be adapted to describe interaction with any web tool, including HTML forms.

{
  "version": "0.1.0",
  "name": "Shinobis Tools",
  "description": "Free web tools for AI-ready content infrastructure",
  "url": "https://shinobis.com",
  "flows": [
    {
      "name": "generate_llms_txt",
      "description": "Generate a valid llms.txt file for any website by providing its URL",
      "steps": [
        {
          "action": "navigate",
          "target": "https://shinobis.com/tools/llmstxt-generator"
        },
        {
          "action": "set_input",
          "selector": "#url-input",
          "description": "Enter the target website URL",
          "input_type": "url",
          "required": true
        },
        {
          "action": "click",
          "selector": "button[type=submit]",
          "description": "Generate the llms.txt file"
        },
        {
          "action": "read_output",
          "selector": "#output-area",
          "output_format": "text/markdown"
        }
      ]
    }
  ]
}

The five-layer stack I built extends to six with agents.json. Identity, accessibility, discovery, permissions, semantic usability, and now execution contracts.

The full specification is at Wildcard AI's repository.