Agent Policy Mistakes That Make a Policy Invalid
Published November 14, 2026 · Reviewed November 2026 · By the Ingenious AI team
The short answer
Five mistakes account for nearly every invalid agent-policy.json file: an action listed as both permitted and disallowed in one rule, two rules sharing one identifier, a missing required field, a value outside its allowed domain, and a last_updated that is not a date. All five are conformance errors, all five are caught by the free validator, and all five happen to careful people — usually at edit time, not at writing time.
Mistake one and two: the contradictions
The overlap. A rule permits download in January; in June someone adds download to the disallowed list without removing it from the permitted one. Neither edit was careless — the file simply never forced the two lists to be read together. Conformance rule 3 does: the intersection must be empty in every rule, and the document is invalid until it is. The duplicate. Two rules for perplexity/agent, written by different people or merged from different branches. Because the spec defines no first-match-wins, the agent cannot choose, so the format refuses the file. Both mistakes share a signature: the JSON is perfectly valid, the fields all look right, and only a relational check — the kind in the five rules — can see them.
Mistakes three and four: the missing and the misspelled
The missing field. Twelve fields are required across the document and its rules; the ones that go missing in the wild are the unglamorous ones — signature, deleted by a tidier who did not know null is a value the format requires, and commercial_terms, dropped when a rule is copied from a sketch. The domain slip. The three-value fields invite near-misses: allowed: "true", default_policy: "closed", commercial_terms: "paid". Each is a word a human reads correctly and a conforming reader must reject, because the domains are what make documents comparable across sites. The generator is immune to both mistakes — it cannot omit a field it always emits, nor misspell a value it offers as a choice — which is the practical argument for generating first and editing second.
Mistake five: the date that is not a date, and the meta-mistake
The unparseable date. last_updated must parse as an ISO-8601 date. "2026-13-01", "next Tuesday", and "October" all fail Rule 5. The field exists to be machine-read; write it like a machine reads it. Behind all five stands the meta-mistake: editing a published policy without re-validating. Every mistake above typically enters through an edit that was never checked, into a file that was valid the day it launched. The fix is procedural and total: validation is part of editing, the way saving is. Teams that run many policies fold the check into batch validation; everyone else needs only the habit and the free tool.
One more non-mistake deserves naming, because owners keep "fixing" it: warnings. An unknown identifier or a custom action name produces a warning, not an error, and the document remains valid. Deleting a deliberate custom action to silence a warning trades real meaning for a quieter report — the distinction is drawn in warnings vs errors, and it is the difference between a file that conforms to the format and a file that merely pleases a checker.
Notice, finally, where every mistake in this guide was born: not in ignorance of the format, but in ordinary editorial work — a paste, a merge, a tidy-up, a deadline. That origin story is the real lesson. Policies are not broken by people who misunderstand AGENT-POLICY; they are broken by workflows that treat a published policy like a static asset instead of a living document with counterparties. The countermeasures are workflow-shaped for the same reason: validation in the merge checklist, the file in the release runbook, the review in a calendar with an owner. Teams that adopt those three habits stop meeting these five mistakes — not because they became cleverer about JSON, but because their process stopped offering the mistakes a way in.
Worked example: a charity's policy breaks twice in one week, quietly
Fictional example. Brightpath Relief, a fictional disaster-relief charity, published a valid policy in January: 3 rules, conditional default, donations pages fenced with submit-form disallowed. In April a campaign edit added a fundraising agent's rule by pasting an existing one — and forgot to change the identifier, creating a duplicate. Four days later a second edit tightened the original rule by adding download to its disallowed list, where download already sat permitted. The site served an invalid policy for 6 days, discovered when a partner operator ran the charity's own file through a validator before relying on it. No harm was done — the partner emailed instead of guessing — but Brightpath's release checklist now has a line it lacked: policy edits validate before deploy, like everything else that ships.
The invalid-policy prevention checklist
- Intersect the lists. Before publishing, check every rule's permitted against its disallowed — empty intersection, every time.
- Count the identifiers. List them; each appears once. Merges and paste-edits are where duplicates breed.
- Count the fields. Seven top-level, five per rule — including
signature, whose correct v0.1 value isnull. - Pick values, don't type them. Generate or copy the three-value domains exactly:
yes,paid-tier,conditional. - Validate every edit. Treat the validator run as part of the edit itself — and validate the live file afterwards.
Keep reading
Validator Warnings vs Errors in AGENT-POLICY v0.1 · How AI Agents Read Your agent-policy.json · What Is an Agent Access Policy (v0.1)? · Spec samples · Conformance · Pricing · All guides
Frequently asked questions
My policy was valid when I published it. Can it become invalid without me touching the file?
The file cannot change itself, but edits around it can: a colleague's well-meant update, a repository merge, a CMS migration that re-serialises the document. Invalidity usually arrives through change, which is why the remedy is validating on every change and periodically re-validating the live copy.
Is an invalid policy worse than no policy?
In one respect, yes. No policy is silence — an agent falls back to its own defaults. An invalid policy is a broken promise: it announces terms it cannot coherently state, and a careful agent must treat the whole document as unreliable rather than guess which half of a contradiction you meant.
What is the single most common invalidating mistake?
The overlapping action lists of conformance rule 3, usually introduced by an edit that touches one list without reading the other. Duplicate identifiers run second. Both are invisible to JSON syntax checking, which is why a schema validator, not a JSON linter, is the right tool.
I listed the same action in both lists on purpose, to mean 'ask me'. What should I do instead?
Use the mechanism the format provides: set the rule's allowed to conditional, or leave the action out of the permitted list and let contact resolve it. Contradiction is not a value in v0.1 — conditional is. The document should say the pause plainly rather than encode it as a conflict.
Do warnings make my policy invalid?
No. Warnings report novelty — identifiers or actions outside the known lists — which the format deliberately tolerates. A file with warnings and no errors is valid and conformant. Only the five error classes invalidate: the conformance-rule violations described in this guide.
Generate a policy — free · Validate a policy · What an agent access policy is