Versioning an Agent Policy: policy_version and last_updated
Published November 14, 2026 · Reviewed November 2026 · By the Ingenious AI team
The short answer
Two fields version an agent-policy.json file. policy_version states which version of the format the document follows — "0.1" today, in a semver-ish "major.minor" shape. last_updated states when the owner last reviewed the decisions inside it, as an ISO-8601 date. One versions the format; the other versions your terms. Agents use both: the first to know which rulebook to read by, the second to know how fresh the answers are.
What does versioning mean for a policy file?
It means the document carries its own context for change. Policies are living decisions — agents graduate from the catch-all, rate limits get tuned, terms evolve — and readers fetch copies at different times. policy_version tells a reader how to interpret the file's structure: v0.1 validators must reject unknown major versions and should warn on unknown minor ones. last_updated tells a reader how much to trust the file's currency: a policy reviewed last month and one untouched for two years may be identically valid and very differently reliable. Together they make a policy a document with a history, not a rumour.
policy_version: the format's contract
The version string is a promise about shape, not content. "0.1" promises the seven required fields, the three-value domains, the conformance rules — the whole of the five conformance rules as v0.1 states them. The asymmetric validator behaviour is deliberate: an unknown major version may change meanings, so readers must refuse it rather than guess; an unknown minor version should only add, so readers warn and continue. Owners have exactly one job here — write the version of the format your document actually follows. Declaring "0.1" while inventing fields from a future draft is how files become unreadable, and the signature field shows the format's preferred alternative: reserved, null, and patient.
last_updated: the owner's signature in practice
If any field functions as v0.1's signature, it is this date. It asserts that on a known day, a human stood behind these decisions. Discipline is simple and total: change anything in the file — a verdict, a number, a sentence — and move the date; review the file and change nothing, and move the date anyway, because the review is the event the field records. The failure mode is the zombie policy: terms written once, drifted from reality, and still declaring an ancient date honestly — which at least tells readers the truth about its staleness. Worse is the undated-feeling file with a fresh date and stale decisions; no validator can detect it, which is why review cadence is an operational habit, not a field.
Versioning across many policies
Owners of several sites inherit a fleet problem: which copies of the policy exist, at which versions, reviewed when? Team-tier change history exists for exactly this — AgentGate's paid tiers add policy change history (Team) and hosted policy URLs (Pro), so versions live in one place rather than in the memory of whoever edited which file. The self-hosted equivalent is a simple register: site, policy_version, last_updated, owner. The format's contribution is that the two facts a register needs are already inside every file, machine-readable, waiting to be collected — one of the quieter reasons the fields are required rather than optional.
There is a temptation to treat versioning as bookkeeping and delegate it to whoever touches the file last. The fleet evidence argues the opposite: versioning is the policy's memory, and memory is what separates an instrument from a snapshot. An owner who can answer "what did this file say in March, and why did it change?" — from the register, the change log, and the dates inside the documents — owns their agent relationships in a way no dashboard confers. That answerability is also what counterparties are quietly pricing when they read your file's dates: a policy with a maintained history is a promise from an organisation that keeps its documents; a policy without one is a rumour with good formatting.
Worked example: a hotel group survives its own rebrand
Fictional example. The Alameda Hotel Group, a fictional group with 5 properties on 5 domains, rebranded in March and updated its trading name everywhere — except, it discovered in June, in the owner field of 2 of its 5 policies. The catch came from its own register: a quarterly sweep listed each file's last_updated, and the two stale files still showed the previous October while their siblings showed March. The fix was 2 edited fields and 2 moved dates. The group's rule since: no policy's last_updated may sit more than one quarter behind the newest in the fleet — a freshness floor enforced by a spreadsheet, made possible because every file declares its own review date.
The versioning checklist
- Declare the true format version.
policy_versionstates the version your document actually follows —"0.1"today. - Date every change. Any edit to any field moves
last_updatedto the day of the edit. - Date every review. A review that changes nothing still moves the date — the review is the recorded event.
- Never fake freshness. A current date over stale decisions is the one versioning sin no validator can catch.
- Register your fleet. If you run several policies, track each file's version and date in one place.
Keep reading
The notice Field: Putting the Honest Scope in the File · Where to Publish agent-policy.json: the /.well-known/ Path · Agent Access Policy Examples · Spec samples · Conformance · Pricing · All guides
Frequently asked questions
What values can policy_version take?
A semver-ish "major.minor" string naming the format version the document follows — "0.1" for every current policy. Validators for v0.1 must reject unknown major versions and should warn on unknown minor versions, so the field is a real compatibility gate, not decoration.
Does last_updated update automatically?
No. Nothing in the format or the file updates itself. The date changes when the owner edits or reviews the policy and writes the new date in. AgentGate's generator stamps the current date on files it builds, but the discipline of moving it on every later review belongs to the owner.
What date format does last_updated use?
An ISO-8601 date, such as "2026-10-18" in the spec's own example. Conformance rule 5 requires that last_updated parses as a date; a malformed string fails validation just as a malformed site URL does.
Can two of my sites share one last_updated rhythm?
They can share a review day, and fleets often do — a quarterly sweep that reviews every policy and moves every date. What each file may not share is a copied date over unreviewed decisions: the date certifies that file's review, not the fleet's calendar.
Will policy_version ever reach 1.0?
The format's roadmap runs through future minor and major versions — a signature profile is the named example of coming change. When a new version ships, owners adopt it by rewriting to the new document shape and declaring the new version; readers handle the transition through the reject-major, warn-minor rule.
Generate a policy — free · Validate a policy · What an agent access policy is