Free plan

← All guides

How AI Agents Read Your agent-policy.json

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

The short answer

An AI agent reads your agent-policy.json in a fixed, simple order: fetch /.well-known/agent-policy.json from your origin; find the rule whose identifier matches its own; if none does, fall back to the generic/* rule and then to default_policy; then read that rule's verdict, its permitted and disallowed actions, its commercial terms, its rate limit, and its data-use terms. Five steps, no interpretation required — which is precisely what the format was designed to make true.

Generate your policy — free · Validate an existing one

What does it mean for an agent to "read" a policy?

It means the agent's planner treats your document as instructions about your site, obtained from you, before it acts. Reading is fetch plus match plus obey-the-stated-terms: the agent does not grade your terms, negotiate with the file, or infer permissions you did not state. This is also where the format's honest limit sits, stated once here and everywhere: reading is what a well-behaved agent does. The policy cannot compel the reading or the obedience — the ignores-your-policy guide covers the other kind — but for agents built to respect declared terms, your file is the declaration they respect.

Steps one and two: fetch and match

The fetch is a single unauthenticated GET of a stable URL, usually before the agent's first substantive action on a site and again when its cached copy ages. The match is exact-string comparison against the rule identifiers — which is why registry spellings matter and why a stray character in an identifier silently reroutes an agent to your catch-all. When the match succeeds, everything else the agent needs is inside that one rule. When it fails, the layering decides: catch-all if you published one, default behind it. Notice what the agent never does: combine rules, average verdicts, or apply one agent's terms to another. Exclusivity of matching is what makes a multi-rule file safe to write.

Steps three to five: verdict, actions, terms

The verdict frames everything. yes means proceed under this rule's conditions; no means do not operate; conditional means stop and contact the owner — the address is in the header's owner.contact, which is why that field must reach a human. The action lists then bound the visit: the agent plans its task against the permitted verbs and treats the disallowed ones as walls — a shopping task that needs checkout against a rule disallowing it becomes a "fill the cart and hand back" task, as the browse-not-checkout guide details. Terms and limits price and pace the work: paid-tier tells the agent's operator a commercial step exists; the rate limit caps its request planning; data_use_terms governs what it may keep afterwards. A well-built agent surfaces all of this to its user when the terms bite — "this store lets me compare but not buy" is a policy read, reported.

What your file looks like from the other side

Reading your own file as an agent would is the cheapest quality check an owner can run. Fetch the well-known URL logged out. Find the rule for the agent you care most about: is it the rule that agent will actually match — right identifier, current verdict? Read the two action lists as a stranger: do they describe the welcome you intend, with the refusals you care about stated rather than implied? Check the dates: does last_updated make the file look maintained or abandoned? Agents and their operators draw confidence from exactly these signals, and every one of them is fixed by editing the file and re-running the validator — no other machinery is involved.

Worked example: one fetch, read five ways

Fictional example. Consider the published policy of Marigold Interiors, a fictional homeware store: conditional default; 4 rules. A shopping agent arrives to compare outdoor furniture for its user. Fetch: 1 request to the well-known path. Match: its identifier has a rule — yes, permitting browse, read, search, shop; disallowing checkout and submit-form; paid-tier terms; 45 requests per minute; data-use terms limiting use to the user's comparison. The agent's plan writes itself: compare 6 furniture sets across 3 categories inside the pace cap, build the cart, stop before payment, and report the terms to its user as the reason. A second agent, unlisted, reads the same file the same day and lands on the catch-all: conditional — it emails the owner instead. One document, two readings, zero ambiguity: the file did the sorting.

The read-it-like-an-agent checklist

  1. Fetch logged out. Retrieve your well-known URL with no session and confirm you get the current JSON.
  2. Match the top agent. Find the rule your most important agent will match — exact identifier, current verdict.
  3. Read lists as a stranger. Grants and refusals should be stated, not implied, for someone with no context.
  4. Follow the conditional. If a verdict says contact first, confirm the header contact reaches a person.
  5. Check the date. last_updated is your file's freshness signal to every reader — keep it honest.

Keep reading

What If an AI Agent Ignores Your Policy? · Should You Let AI Agents Shop on Your Site? · Agent Policy vs robots.txt, Compared · Spec samples · Conformance · Pricing · All guides

Frequently asked questions

When does an agent fetch the policy?

Before operating on a site — typically ahead of its first substantive action, and again when its cached copy ages or its operator refreshes it. The format cannot force the fetch; it guarantees that when an agent looks, the terms are at one known address in one known shape.

What if two rules seem to apply to one agent?

They cannot, in a valid document. Matching is by exact identifier, each identifier appears at most once (duplicates are a conformance error), and an agent reads either its named rule or the generic/* catch-all — never both, never a blend.

Does the agent read the notice field?

It is part of the document, and operators and summarising agents do read it — which is why the notice carries context like the honest-scope line and pointers to licensing contacts. The machine-actionable reading, though, comes from the structured fields: verdict, actions, terms, limits.

What does an agent do when my verdict is conditional?

It pauses and routes to the owner contact in your header. v0.1 defines no real-time negotiation protocol — the spec says so — so contact means the operator-level conversation your contact address starts. A conditional pointing at an unmonitored inbox is a refusal by neglect; staff the address.

Can an agent misunderstand a valid policy?

The format minimises the surface for it: closed value domains, disjoint action lists, exclusive matching. Residual ambiguity lives where judgement lives — custom action names and free-text data-use terms — which is why those should be written plainly. If an operator reports a surprising reading, fetch your live file first; the disagreement is often a stale copy.

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

← Back