Free plan

← All guides

How to Write an agent-policy.json File, Step by Step

Published November 14, 2026 · Reviewed November 2026 · By the Ingenious AI team

The short answer

Writing an agent-policy.json file means making five decisions and encoding them in one small JSON document: who you are, what your default answer is, which named agents get their own rules, what each rule permits and forbids, and on what terms. This guide walks the document top to bottom in the order the AGENT-POLICY v0.1 spec defines it, so the file you finish with is the file the validator expects.

Generate your policy — free · Validate an existing one

Step one: the header fields

Open with the fields that say whose document this is. policy_version is "0.1". site is your canonical origin — the https:// URL of the site the policy governs, matching the origin you will serve the file from. owner is an object with a human-readable name and a contact — an email address or URL that an agent operator can use to reach a person, because the conditional verdict is meaningless if nobody answers it. Finish the header at the end of the document rather than the start: last_updated takes today's date when you publish, and signature is null in v0.1. Add the optional notice if you want the honest-scope line — that this file declares terms and does not enforce them — inside the document itself.

Step two: choose the default before the exceptions

default_policy is the answer every unnamed agent gets, so choose it before writing any rule: allow if your site is open by design, block if no agent should operate at all, or conditional — contact the owner first — if you want a conversation before access. Most first-time authors pick conditional, and the published store sample shows why: it keeps strangers politely paused while named agents with negotiated rules work immediately. The default policy guide works through the choice in full. Write the default down as a sentence a colleague could defend — "unknown agents ask first" — because every rule you write next is an exception to it.

Step three: write rules that say one thing each

Each object in agents is one rule for one identifier. Set allowed, then the two action lists. Work from the suggested vocabulary — browse, read, search, summarize, quote, shop, checkout, book, submit-form, download, api-call, crawl-full-site — and add a custom action name only when none of the twelve fits; unknown names earn a validator warning, not an error, so the file still conforms. The two hard rules of rule-writing: never put the same action in both lists of one rule, and never write two rules with the same identifier. Both are conformance errors, covered in the common mistakes guide. If you want every unnamed agent covered explicitly as well as by the default, add a generic/* rule — the store sample does exactly this, holding the catch-all to conditional at 10 requests per minute.

Then the terms. commercial_terms is one of free, paid-tier, or contact — pick per rule, not per site; the samples mix them freely. Add rate_limit as {"requests_per_minute": N} where you care about load, or leave it out (or null) where you do not. Write data_use_terms as a sentence a lawyer and an engineer would both parse the same way: what may be retained, resold, or trained on. "Product data may be used for price comparison only. No resale. No training on product images." is the register to aim for.

Step four: assemble, validate, publish

Assemble the document and read it once as an agent would: find your rule, read the verdict, read the two lists. Then machine-check what your eyes cannot: paste the file into the free validator and fix every error it reports — warnings you may consciously accept. Publish at /.well-known/agent-policy.json as application/json, reachable without authentication, and fetch the live URL once to confirm the server returns the document you validated rather than a redirect, a login page, or last month's draft. If writing JSON by hand sounds like the slow path, it is: AgentGate's free generator builds the same document from a short questionnaire, which is how the file in the worked example below was produced.

Worked example: a walking-tour company writes its file in one sitting

Fictional example. Cobblestone Walks, a fictional walking-tour company taking bookings in three cities, wrote its policy in 40 minutes. The header names the company with a bookings-desk contact. The owner chose a conditional default, then wrote 4 rules: openai/agent and google/gemini-agent may browse, read, search, and book free at 30 requests per minute; perplexity/agent may read and quote free at 30 per minute with data-use terms requiring a link back; generic/* is conditional at 10 per minute. submit-form is disallowed in every rule, so agents can hold a tour slot through the booking action but cannot post to the contact or reviews forms. The first validation run flagged one error — search sat in both lists of the catch-all rule — which took one edit to fix. The published file is 58 lines.

The five-step writing checklist

  1. Header first. Fill policy_version, site, and owner with a contact a human actually monitors.
  2. Default second. Pick allow, block, or conditional and be able to defend it in one sentence.
  3. One rule per agent. Unique identifiers, one verdict each, permitted and disallowed lists kept strictly apart.
  4. Terms on every rule. commercial_terms always; rate limit and data-use terms wherever they matter.
  5. Validate the live file. Check the draft, publish at the well-known path, then fetch and re-validate what the server actually serves.

Keep reading

default_policy Explained: allow, block, or conditional · Per-Agent Rules in agent-policy.json, Explained · How to Tell AI Agents What They May Do · Spec samples · Conformance · Pricing · All guides

Frequently asked questions

Can I write agent-policy.json by hand, or do I need the generator?

By hand is fine — the document is plain JSON with seven required top-level fields, and the spec's samples are short. The free generator exists to remove transcription errors: it asks the same questions this guide asks and emits a conforming file, which you can still edit afterwards.

What order do the fields go in?

JSON object order does not matter to the validator or to agents. Write in the order that helps you think: header, default, rules, review date. What matters is that every required field is present with a value from its allowed domain.

How long should the file be?

As long as your decisions require and no longer. The published samples run from a handful of lines (the bank sample is a block default with an empty agents list) to a few dozen for a store with three rules. Most real sites land between 30 and 80 lines.

What if I do not know an agent's identifier?

You do not need to name every agent. The default_policy covers everyone you do not name, and a generic/* rule lets you speak to all unnamed agents explicitly. Identifiers use vendor/agent form; the v0.1 registry lists six known agents plus the catch-all, and unknown identifiers only ever earn a warning.

When do I update last_updated?

Every time you review the policy — change a rule or confirm the terms still stand. The field is the document's freshness signal: it tells an agent which rulebook the file follows and how recently a human stood behind the decisions in it.

Generate a policy — free · Validate a policy · What an agent access policy is

← Back