---
title: "What is agent-permissions.json? A plain-English guide"
description: What agent-permissions.json is, what goes in the file, and why AI agents check it — verb-and-selector rules, RFC 2119 guidelines, the strict flag, the invalid-means-absent rule, and how it differs from robots.txt.
last_updated: 2026-07-17
canonical_url: https://agent-ready.dev/what-is-agent-permissions-json
---
# What is agent-permissions.json? A plain-English guide
> agent-permissions.json is a JSON manifest, defined by the LAS-WG at v1.0.0, that declares which actions AI agents may and may not take on your site.
**agent-permissions.json** is a JSON manifest that declares which actions AI agents may and may not take on your site. Browsing agents no longer just read pages — they click buttons, fill forms, upload files, and follow links on a person's behalf. robots.txt has nothing to say about any of that: it governs which URLs may be *fetched*, not what happens inside a loaded page. agent-permissions.json is the action-level complement, defined by the [Lightweight Agent Standards Working Group](https://github.com/las-wg/agent-permissions.json) (LAS-WG) at v1.0.0 with a complete JSON Schema. Agents discover it at `/.well-known/agent-permissions.json`, or wherever a `` tag points.
## 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.
```json
{
"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.
## The invalid-means-absent rule (why one typo voids the file)
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. 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](https://agent-ready.dev/agent-permissions-generator) rather than hand-writing.
## 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.
| | agent-permissions.json | robots.txt | agents.json |
|---|---|---|---|
| Governs | Actions in a loaded page | Which URLs may be fetched | API operations to call |
| Granularity | Verb + CSS selector | URL path | OpenAPI operation |
| Written for | Agents driving your UI | Crawlers | Agents calling your API |
| Typical statement | "Don't submit forms without a human" | "Don't crawl /admin" | "Search products like this" |
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.
## 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.
## How do I create and validate one?
Build the file with the [agent-permissions.json generator](https://agent-ready.dev/agent-permissions-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](https://agent-ready.dev/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.
## Frequently asked questions
### What is agent-permissions.json?
agent-permissions.json is a JSON manifest, defined by the Lightweight Agent Standards Working Group (LAS-WG) at v1.0.0, that declares which actions AI agents may and may not take on your site. Where robots.txt governs which URLs a crawler may fetch, agent-permissions.json governs what an agent may do inside a page it has loaded: resource_rules bind one of 16 verbs (click_element, submit_form, execute_script, …) and a CSS selector to an allow or deny, and action_guidelines carry RFC 2119 directives for higher-level behaviour. It is served at /.well-known/agent-permissions.json.
### What goes in an agent-permissions.json file?
Two required fields: metadata (a semver schema_version and an ISO-8601 last_updated) and strict, the boolean that sets the default for anything you don't list — true denies unlisted actions, false allows them. Three optional blocks: resource_rules (element-level verb + CSS selector + allowed, with optional modifiers like human_in_the_loop and rate_limit), action_guidelines (MUST / MUST NOT / SHOULD / SHOULD NOT directives with a description), and api (OpenAPI, MCP, or A2A endpoints agents should use instead of driving the UI). The schema forbids any other property.
### How is agent-permissions.json different from robots.txt?
robots.txt governs fetching — which URLs a crawler may request — at URL-path granularity. agent-permissions.json governs acting — clicking, typing, submitting, uploading, running script — at CSS-selector granularity inside a loaded page. A site can be fully open to crawling and still forbid agents from submitting its forms. They are complements: neither can express the other's policy, and a well-configured site ships both.
### Why is an invalid agent-permissions.json worse than no file?
The spec instructs consumers to treat a file that fails schema validation as absent and to grant no permissions from it. So an invalid file does not fail open or fail closed — it does nothing at all, while you believe a policy is in force. Because the schema sets additionalProperties: false throughout, a single invented field invalidates the whole document. The same trap applies to verbs: an unrecognised verb MUST be treated as disallowed, so a typo silently forbids the thing you meant to permit.
### Do AI agents actually respect agent-permissions.json?
It is early. The spec is complete and enforceable — a published v1.0.0 with a full JSON Schema — but it comes from a young working group and is not yet ratified by a formal standards body, and browsing agents are only beginning to look for it. Publishing one is low-cost insurance: it states your policy on the record for the agents that do check it (and the scanners that grade agent-readiness, including our C7 check), and it costs a small JSON file if adoption stalls.
### How do I create and validate an agent-permissions.json?
Build it with the Agent Ready agent-permissions.json generator, which only emits fields the v1.0.0 schema defines and can probe your site so the api block references only endpoints that verifiably exist. Serve it at /.well-known/agent-permissions.json as application/json. Then run the agent-permissions validator: it checks the live file against the full schema and — because it scans the whole site — also catches unparseable selectors, contradictory rules, no-op policies, and api references to manifests you don't actually publish.
## The agent-permissions.json toolchain
- Learn: [What is agent-permissions.json?](https://agent-ready.dev/what-is-agent-permissions-json)
- Generate: [agent-permissions.json generator](https://agent-ready.dev/agent-permissions-generator)
- Validate: [agent-permissions.json validator](https://agent-ready.dev/agent-permissions-validator)
- Scan: [Agent readability score](https://agent-ready.dev/agent-readability-score)
---
Read the full guide on the web:
Scan your site:
## Sitemap
See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.