Validator Warnings vs Errors in AGENT-POLICY v0.1
Published November 14, 2026 · Reviewed November 2026 · By the Ingenious AI team
The short answer
An AGENT-POLICY validator speaks in two voices. Errors report broken conformance rules — a missing field, a contradiction, a duplicate — and make the document invalid. Warnings report novelty — an agent identifier outside the v0.1 registry, an action outside the suggested vocabulary — and leave the document fully valid. The split is the format's growth mechanism: strict about structure, permissive about vocabulary, so the ecosystem can invent new agents and new verbs without breaking old files.
What is a validator warning?
A warning is the validator saying: this conforms, and you should know it steps outside the lists I know. The two lists in question are the identifier registry (six named agents plus the catch-all) and the suggested action vocabulary (twelve verbs). Both are declared non-exhaustive in the spec itself. When your file names a seventh agent or a thirteenth verb, the validator cannot call it an error without betraying the spec — the spec told it not to. So it warns: a flag for a human to read, attached to a document that passes. AgentGate's validator reports the two classes separately for exactly this reason.
Why errors are errors
Each error class maps to a conformance rule whose violation makes a document unreadable-as-intended. Missing fields (Rule 2) leave questions the format promised to answer. Domain violations (Rule 2) break the shared vocabulary that makes files comparable. Overlaps (Rule 3) are undecided decisions. Duplicates (Rule 4) are unresolvable ambiguity. Format failures (Rule 5) break machine-readability of the policy's subject and freshness. In every case a reader downstream — the agent the file addresses — would have to guess. Errors exist to move the guessing back to the author, where it belongs. The full taxonomy is in the five conformance rules and the mistakes guide.
Why warnings are not errors — the growth argument
Imagine the alternative: unknown identifiers as errors. Every newly launched agent would begin life un-nameable — no owner could write it a rule until a registry update shipped, and every validator release would invalidate intentions across the web. The format would have frozen its ecosystem at the six agents its authors happened to know in October 2026. Warnings invert that: the registry becomes advice, the vocabulary becomes a starting set, and innovation costs a yellow flag instead of a red one. The design has a price — owners must actually read warnings, since a warning is also where typos hide — but the price is the correct one to pay, and it is paid by the party with the context to judge: the author.
Reading warnings like an editor
Every warning deserves one of two verdicts, recorded at least in the reader's head. Deliberate: the new agent your partner just launched; the custom verb — bid, reserve, stream — that names behaviour the twelve do not. Keep it; the file is richer for saying exactly what it means. Accidental: anthropic/claude where the registry's anthropic/claude-agent was meant; check-out where checkout exists. Fix it; a misspelled known name is worse than a new one, because the agent it half-names will not find its rule. The discipline is identical to spell-checking prose: the checker flags, the author decides, and a report with zero warnings is not the goal — a file with no undecided warnings is.
There is a cultural point underneath the mechanics, and it decides whether the two-voice system works in a given team. Warnings survive only where raising a flag is cheap and respected — where the reviewer who pauses over a yellow line is thanked rather than hurried. Teams that treat every warning as a defect to be eliminated by Friday will, predictably, start eliminating the information instead: custom verbs deleted, new agents left unnamed, files kept artificially inside the known lists while the business leaks out of them. The format's designers chose warnings as the growth mechanism precisely because growth is untidy. A validator report with a few owned warnings is the signature of a policy that describes a real, changing business; a permanently silent report, in a moving ecosystem, should itself be read as a warning.
Worked example: a streaming service keeps one warning on purpose
Fictional example. Lantern Play, a fictional independent film-streaming service with 4,800 titles, validates its policy quarterly. Its report has carried the same single warning for a year: the custom action stream, used in 2 rules to distinguish streaming a film from download-ing one — a distinction its licensing depends on and the suggested vocabulary does not draw. Each quarter the reviewer does three things: confirms stream is still deliberate, scans the rest of the report for new warnings (one quarter caught a contractor's perplexity/ agent with a stray space — an accidental warning, fixed in a minute), and moves last_updated. One warning, permanently owned, is what a healthy report looks like for a service whose business needed a thirteenth verb.
The warnings-and-errors checklist
- Zero errors, always. A document with any error is invalid; fix errors before anything else ships.
- Read every warning. Each one gets a verdict: deliberate or accidental.
- Keep deliberate novelty. New agents and custom actions are the format growing; do not delete meaning to silence a flag.
- Fix accidental novelty. Misspelled registry names and near-miss verbs get corrected to the known forms.
- Re-check quarterly. A warning you've owned for a year still gets re-decided at each review — cheap vigilance, real catches.
Keep reading
How AI Agents Read Your agent-policy.json · What If an AI Agent Ignores Your Policy? · How to Tell AI Agents What They May Do · Spec samples · Conformance · Pricing · All guides
Frequently asked questions
Is a policy with warnings valid?
Yes. Validity is decided by errors alone. A document carrying warnings about an unregistered identifier or an unsuggested action, and no errors, is fully conformant — the spec defines both lists as non-exhaustive precisely so that novelty warns instead of failing.
What triggers a warning?
Two things: an agent identifier outside the v0.1 registry (six named agents plus generic/*), and an action name outside the suggested twelve-verb vocabulary. Both are reported as warnings rather than errors so the format can absorb new agents and new behaviours without breaking published files.
Should I aim for zero warnings?
Aim for zero undecided warnings. A custom action that names real behaviour your licences depend on is a warning worth keeping permanently. A warning you have never read is a liability — it might be a typo that leaves a named agent unable to find its rule. The verdict matters, not the count.
Can a warning become an error in a future version?
Vocabulary can be promoted: if a future registry adopts an identifier, files naming it simply stop warning. The reverse — a tolerated name becoming an error — would break the format's growth contract and its back-compatibility posture, so the design pressure runs firmly the other way.
Where do I see warnings for my policy?
In the validator's report. AgentGate's free validator separates errors from warnings in its conformance output, and the batch API returns the same distinction per policy for fleets checking many files at once. Bring the document; the validator makes no network requests.
Generate a policy — free · Validate a policy · What an agent access policy is