What is agent-permissions.json?

What goes in an agent-permissions.json file?

Two fields are required: metadata (a semver schema_version and an ISO-8601 last_updated) and strict — the default for everything you don’t list. true denies unlisted actions; false allows them. Three optional blocks do the real work:

• resource_rules — element-level permissions. Each rule binds a verb (one of 16, from read_content to submit_form and execute_script), a CSS selector, and allowed true or false. Optional modifiers add conditions: human_in_the_loop, rate_limit, burst, and a time_window.
• action_guidelines — behaviour-level policy as RFC 2119 directives (MUST, MUST NOT, SHOULD, SHOULD NOT) with a natural-language description, fed to the agent as instruction rather than enforced at the browser.
• api — the escape hatch: OpenAPI, MCP, or A2A endpoints agents should use instead of driving your UI.

{
  "metadata": {
    "schema_version": "1.0.0",
    "last_updated": "2026-07-17T00:00:00Z",
    "author": "Acme"
  },
  "strict": false,
  "resource_rules": [
    { "verb": "read_content", "selector": "*", "allowed": true },
    { "verb": "execute_script", "selector": "*", "allowed": false },
    {
      "verb": "submit_form",
      "selector": "#contact-form",
      "allowed": true,
      "modifiers": { "human_in_the_loop": true }
    }
  ],
  "action_guidelines": [
    {
      "directive": "MUST NOT",
      "description": "Create an account on a person's behalf without an authenticated human session."
    }
  ],
  "api": [
    {
      "type": "openapi",
      "endpoint": "https://acme.com/openapi.json",
      "description": "Use the REST API instead of driving the UI."
    }
  ]
}

Serve it as application/json. The schema forbids any property it doesn’t define — which matters more than it sounds, as the next section explains.

The invalid-means-absent rule (why one typo voids the file)

The spec has an unusually harsh failure mode. On validation failure, a consumer “SHOULD treat the file as absent and MUST NOT grant additional permissions based on it”. An invalid file therefore doesn’t fail open or fail closed — it does nothing, while you believe a policy is in force. And because the schema sets additionalProperties: false throughout, one invented field invalidates the entire document. Verbs have the same sharp edge: an unrecognised verb MUST be treated as disallowed, so click_elment doesn’t loosely mean click_element — it silently forbids the click you meant to permit. This is why the file is worth generating against the real schema rather than hand-writing: we learned it the hard way when our own hand-written file turned out to be invalid, and every compliant agent had been discarding it.

How is agent-permissions.json different from robots.txt and agents.json?

Three files, three layers. robots.txt controls what may be fetched, agent-permissions.json controls what may be done in the page, and agents.json maps an API for agents that skip the UI entirely.

A site can be fully open to crawling and still forbid agents from executing script or submitting forms — neither file can express the other’s policy, so ship the ones that apply. For the API-mapping side, see the agents.json generator.

Do AI agents actually respect agent-permissions.json?

Honestly: it is early. The spec is complete and enforceable — a published v1.0.0 with a full JSON Schema — but the working group is young, it isn’t ratified by a formal standards body, and browsing agents are only beginning to look for it. Publishing one is low-cost insurance: your policy is on the record for the agents that do check it and for the scanners that grade agent-readiness (our C7 check validates it on every scan), and if adoption stalls the cost was a small JSON file. Adopting early is a bet that the spec ratifies; early adopters set the norms.

How do I create and validate one?

Build the file with the agent-permissions.json generator — it emits only fields the v1.0.0 schema defines, and it can probe your site so the api block only references endpoints that verifiably exist. Serve it at /.well-known/agent-permissions.json, then run the agent-permissions validator against your live site. Because the validator scans the whole site — not just the file — it also catches what a schema alone cannot: selectors that parse but match nothing, contradictory rules, no-op policies, and api references to manifests you don’t actually publish.