Free plan

← All guides

What Is the agent-policy.json File?

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

The short answer

The agent-policy.json file is a single JSON document a website publishes at /.well-known/agent-policy.json to state its terms for AI agents: which agents may operate, which actions they may take, and on what commercial terms. It follows the AGENT-POLICY v0.1 format defined by AgentGate. An agent — or its operator — fetches that one stable URL, without authentication, and reads the owner's answer before doing anything else on the site.

Generate your policy — free · Validate an existing one

What is agent-policy.json, in one sentence?

An agent policy is a machine-readable declaration, written by the site owner, that answers three questions for every AI agent that arrives: are you welcome, what may you do, and what does it cost? If robots.txt is the notice a site pins up for crawlers, agent-policy.json is the notice it pins up for agents — except this notice can also name actions, rate limits, and payment terms, because agents do more than fetch pages: they search, shop, book, and call APIs.

What does the file actually contain?

Seven top-level fields are required. policy_version says which version of the format the document follows — "0.1" today. site is the canonical origin the policy speaks for, and owner names the owner and a contact an agent operator can actually use. default_policy — allow, block, or conditional — is the answer for every agent the file does not name. The agents array holds per-agent rules that override the default for named agents. last_updated records when the owner last reviewed the terms, and signature is a required placeholder whose v0.1 value is null. An optional notice field lets the owner restate, in plain words, that the file is a declaration rather than a lock.

Each rule inside agents speaks to one agent, identified in vendor/agent form such as openai/agent or the catch-all generic/*. A rule states its verdict in allowed (yes, no, or conditional), lists permitted_actions and disallowed_actions, sets commercial_terms (free, paid-tier, or contact), and may add a rate_limit in requests per minute and plain-language data_use_terms. The full anatomy, rule by rule, is in the worked policy examples.

Who reads the file, and when?

The reader is software. A well-behaved agent checks the well-known URL before operating on a site it has not visited — or before returning — and plans its behaviour around the answer: a yes rule with shop permitted means it may compare products; checkout in the disallowed list means it stops before paying and hands that step back. Agent operators and site owners are the second audience: operators read policies to know what their agents are allowed to do, and owners read other sites' policies — including the three published spec samples — before writing their own.

There is also a third, unglamorous reader: the validator. Because the file is JSON with a fixed schema, a machine can check it mechanically — required fields present, values inside their domains, no contradictions. That is what AgentGate's free validator does, and it is why the format stays small: everything in the file is either a decision an owner must make or a fact a machine must be able to check.

What the file is not

The spec's first section is an honest-scope warning, and it applies to every claim made about this file. A policy is declaration plus discovery, not enforcement. Publishing one does not block a single request, authenticate a single agent, or create a legal opinion — a validator's "valid" verdict means schema conformance only. Agents that ignore the file are a problem for bot detection, web application firewalls, and legal process, all of which v0.1 deliberately leaves out of scope. What the file does is narrower and, for the agents that do read it, decisive: it turns a site owner's terms from something an agent must guess into something it can fetch, parse, and be measured against.

Worked example: a seed supplier writes its first file

Fictional example. Tierra Verde Seeds, a fictional seed supplier in Belize selling through a small web shop, kept getting support email from shopping agents asking whether they could compare pack prices. The owner answered the question once, permanently, in a file: default_policy set to conditional, one rule for generic/* permitting browse, read, and search at 20 requests per minute with data_use_terms limiting use to price comparison, and checkout plus submit-form disallowed for everyone. The file runs to 31 lines. In the first month after publishing, the shop's contact inbox received 6 messages from agent operators negotiating access — exactly the conversations the conditional default is designed to start — and zero confused "may we?" emails, because the answer was already published where agents look for it.

The agent-policy.json starter checklist

  1. Decide the default. Choose allow, block, or conditional for agents you do not name.
  2. Name the agents you care about. Add one rule per agent identifier, plus a generic/* catch-all if you want strangers covered explicitly.
  3. Split the actions. List permitted and disallowed actions per rule — and never the same action in both lists.
  4. State the terms. Set commercial_terms, an optional rate limit, and plain-language data-use terms.
  5. Publish and validate. Serve the file at /.well-known/agent-policy.json and run it through the free validator before and after it goes live.

Keep reading

How to Write an agent-policy.json File, Step by Step · default_policy Explained: allow, block, or conditional · What Is an Agent Access Policy (v0.1)? · Spec samples · Conformance · Pricing · All guides

Frequently asked questions

Where does agent-policy.json live on a website?

At one fixed address: /.well-known/agent-policy.json on the site's own origin, served as application/json and reachable without authentication. The fixed location is the discovery mechanism — an agent never has to guess where a site keeps its terms.

Is agent-policy.json the same as robots.txt?

No. robots.txt tells crawlers which paths they may fetch. agent-policy.json tells AI agents which named agents may operate, which actions they may take, on what commercial terms, and at what requested rate limit. A site can publish both; they answer different questions.

Do I need an account or a paid plan to publish one?

No. The format is a published spec, the generator and the single-policy validator on AgentGate are free and unlimited, and you can host the file on your own site yourself. Paid tiers add conveniences — batch validation and hosted policy URLs — not permission to use the format.

What happens if my file has an error in it?

The document is invalid under the v0.1 conformance rules — for example if a required field is missing, or one action appears in both the permitted and disallowed lists of the same rule. Run the file through the free validator; it reports errors separately from warnings, and only errors invalidate the document.

Does publishing the file stop agents that ignore it?

No, and the spec says so plainly: a policy is a declaration, not an enforcement mechanism. It states your terms in the standard form agents can discover. Blocking agents that ignore declared terms is a separate concern — bot detection, firewall rules, and legal process — outside the v0.1 scope.

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

← Back