agent-permissions.json generator
robots.txt says what agents may fetch. This file says what they may do — click, type, submit, upload — and one invented field voids the whole policy, so build it against the real schema.
{
"metadata": {
"schema_version": "1.0.0",
"last_updated": "1970-01-01T00:00:00.000Z"
},
"strict": false,
"resource_rules": [
{
"verb": "read_content",
"selector": "*",
"allowed": true
},
{
"verb": "read_metadata",
"selector": "*",
"allowed": true
},
{
"verb": "follow_link",
"selector": "*",
"allowed": true
},
{
"verb": "execute_script",
"selector": "*",
"allowed": false
},
{
"verb": "upload_file",
"selector": "*",
"allowed": false
}
]
}
Next steps
Save this as /.well-known/agent-permissions.json (served as application/json), then validate it against your live site — the validator also checks your selectors match real elements and your api entries resolve — and run a full agent-readability scan.
Last updated
Why generate this file instead of writing it by hand?
Because 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” — and the schema sets additionalProperties: false throughout, so a single invented field invalidates the entire document. A hand-written file with one extra key does not fail open or closed; it silently does nothing, while you believe a policy is in force. This generator emits only fields the published v1.0.0 JSON Schema defines, so its output cannot hit that trap. When we rebuilt our validator around the real schema, our own hand-written file turned out to be invalid — every compliant agent had been discarding it.
The 16 verbs, in plain English
The schema defines a closed set of 16 interaction verbs — and an unknown verb MUST be treated as disallowed, so a typo forbids the thing you meant to permit. What the spec doesn’t tell you is which verbs are safe to leave open on a public site. Grouped by what they risk:
| Verb | Allows an agent to | Deny it when |
|---|---|---|
| Everything | ||
| all | Every interaction at once. A single rule on `all` sets a blanket allow or deny for the matched elements. | Useful as a deny on a sensitive region (a checkout flow, an admin panel) so nothing inside it is agent-operable. |
| Observe — reading, no side effects | ||
| read_content | Read the visible text and content of the matched elements. | Denying this on a public site mostly breaks legitimate assistants; deny it only on regions that should never reach an AI answer. |
| read_metadata | Read non-visible attributes — data-* attributes, ARIA labels, structured markup. | Rarely worth denying: metadata is how agents disambiguate your UI. |
| Navigate — moving through the page | ||
| follow_link | Follow hyperlinks from the matched elements to other pages. | Deny on logout links or destructive one-click actions disguised as links. |
| scroll_page | Scroll the page or a scrollable region to reveal more content. | Almost never — denying it hides content agents may legitimately read. |
| Interact — actions with side effects | ||
| click_element | Click buttons and other interactive elements. | Deny on anything that commits state — purchase buttons, delete buttons — or require a human in the loop instead. |
| set_input_value | Type into or set the value of form fields. | Deny on payment fields and credential inputs. |
| submit_form | Submit forms on the page. | The classic human-in-the-loop candidate: allow form filling but gate submission on a human confirmation. |
| execute_script | Run script in the page context. | Deny by default. Agents have no routine reason to run code inside your page, and allowing it hands over the whole DOM. |
| Media — playback control | ||
| play_media | Start audio or video playback. | Deny if playback triggers billing or consumes metered quota. |
| pause_media | Pause audio or video playback. | Rarely worth denying. |
| mute_media | Mute audio. | Rarely worth denying. |
| unmute_media | Unmute audio. | Rarely worth denying. |
| Data — moving files and text in or out | ||
| upload_file | Attach and upload files through file inputs. | Deny unless your site is built around user uploads — it is an easy abuse channel. |
| download_file | Download files the page offers. | Deny on metered or licensed downloads. |
| copy_to_clipboard | Copy page content to the clipboard. | Rarely worth denying on public content. |
strict is the biggest decision in the file
Everything you don’t list falls to the default, and strict chooses it: true denies anything unlisted, false allows it. Public content sites usually want strict: false with explicit denies on the dangerous verbs (execute_script, upload_file); transactional sites want strict: true with explicit allows for reading. The generator warns about both degenerate corners: allow-by-default with no rules is a no-op file, and deny-by-default with no allows blocks even reading.
The api block is an escape hatch — verify it
The most constructive part of the spec: api[] tells agents “don’t drive my UI, call this instead” — an OpenAPI document, an MCP server, or an A2A endpoint. But a reference to a manifest your site doesn’t actually publish is a broken escape hatch: the agent falls back to exactly the interaction path you were steering it away from. Our scanner’s C7 check flags those dangling references on live sites; this generator closes the loop from the other side by probing your site and only offering entries it verified moments ago.
Frequently asked questions
- What is agent-permissions.json?
- agent-permissions.json is a permission manifest for web agents, defined by the Lightweight Agent Standards Working Group (LAS-WG) at v1.0.0. Where robots.txt says which URLs a crawler may fetch, agent-permissions.json says which actions an agent may take once it is on the page: 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.
- How is agent-permissions.json different from robots.txt?
- robots.txt governs fetching — which URLs a crawler may request. agent-permissions.json governs acting — what an agent may do inside a page it has already loaded: click, type, submit, upload, run script. A site can be fully open to crawling and still forbid agents from executing script or submitting its forms. The two files are complements, not alternatives, and neither can express the other's policy.
- What does the strict flag do?
- strict sets the default for every interaction you did not explicitly list. strict: true means deny by default — an agent may only do what a rule allows. strict: false means allow by default — everything is permitted except what a rule forbids. It is the single biggest decision in the file: with strict: false and no rules, the policy is a no-op; with strict: true and no rules, agents may not even read your content.
- 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. An invalid file therefore does not fail open or fail closed — it does nothing, while you believe a policy is in force. And the schema sets additionalProperties: false throughout, so one invented field invalidates the whole document. That is the case for generating the file rather than hand-writing it: this generator only emits fields the schema defines, so its output cannot hit that failure mode.
- What happens if I use a verb the spec doesn't define?
- The spec says an unrecognised verb MUST be treated as disallowed. So a typo — say click_elment — does not loosely mean what you intended; it silently forbids the interaction you meant to permit. The generator only offers the 16 defined verbs, so this cannot happen in its output.
- Why does the generator ask for my site URL?
- To fill the api[] block with endpoints that verifiably exist. api[] points agents at an OpenAPI, MCP, or A2A endpoint they should use instead of driving your UI — but a reference to a manifest your site doesn't publish is a broken escape hatch that sends agents straight back to the interface you were steering them away from. The generator probes your site's real manifests (/.well-known/mcp.json, /.well-known/agent-card.json, /openapi.json and friends) and only offers entries it just fetched. Our scanner's C7 check flags dangling api references on other sites; files built here can't have them.
- Where do I put the file?
- Serve it at /.well-known/agent-permissions.json with Content-Type: application/json. Alternatively, point to it from your pages with a <link rel="agent-permissions" href="…"> tag. After publishing, run the agent-permissions validator to confirm the live file parses, matches the schema, and — if you scan your whole site — that your selectors match real elements.