Per-Agent Rules in agent-policy.json, Explained
Published November 14, 2026 · Reviewed November 2026 · By the Ingenious AI team
The short answer
A per-agent rule is one object in the agents array of an agent-policy.json file, speaking to exactly one agent identifier. It carries that agent's verdict (allowed: yes, no, or conditional), its permitted and disallowed action lists, its commercial terms, and optionally a rate limit and data-use terms. Where a rule exists, it — not default_policy — is the answer that agent reads.
What is a per-agent rule?
It is the unit of discrimination in the format: the mechanism that lets a site treat agents differently instead of issuing one verdict for all of them. The store sample in the spec is three rules deep — one agent shops on a paid tier at 60 requests per minute, one reads and quotes free at 30, and the catch-all waits for contact at 10. Same site, same file, three different answers, each readable by the agent it names without ambiguity. If the default policy is the sign on the door, rules are the named entries on the guest list.
The anatomy of one rule
Five fields are required. identifier names the agent in vendor/agent form — see agent identifiers explained. allowed is the verdict. permitted_actions and disallowed_actions partition behaviour: what is granted, and what is explicitly out of bounds. commercial_terms prices the relationship as free, paid-tier, or contact. Two optional fields refine it: rate_limit, an object holding requests_per_minute, and data_use_terms, a plain-language sentence about retention, resale, and training. A rule with allowed set to no may carry an empty permitted list — the blog sample's single rule does exactly that while listing seven disallowed actions, spelling out the refusal.
How an agent picks its rule
The reading algorithm is deliberately boring: fetch the file, look for the rule whose identifier matches you, and if none does, fall back to the generic/* rule if one exists and the default_policy behind it. There is no scoring, no fuzzy matching, and — critically — no first-match-wins: the spec makes duplicate identifiers a conformance error precisely so an agent never has to guess which of two rules for it is real. That is why how agents read your policy can be described in one paragraph, and why rule hygiene — one agent, one rule, no contradictions inside it — is the whole craft of writing them.
Writing rules that stay readable
Three habits keep a ruleset parseable as it grows. Mirror your intent, not your org chart: group agents by the answer they get, but still write one rule per identifier — the format has no rule-sharing syntax, and copy-pasted clarity beats clever compression. Keep the two lists disjoint in every rule; an action in both is an invalid document, not a nuance. Let the catch-all carry the strangers: a generic/* rule with real terms turns your default from a bare verdict into stated conditions. When a ruleset grows past what one file review can hold — many sites, many agents — the operational patterns are in policies for multiple websites and batch validation.
A final habit worth adopting early: review your rules in the order an agent population experiences them, not in the order you wrote them. Sort them mentally into welcomes, pauses, and refusals, and read each group as a class — do the welcomes share a coherent philosophy of pace and terms? Do the refusals each have a story you could tell the refused agent's operator without embarrassment? Rules accumulate one negotiation at a time, and accumulation is how incoherence enters: the partner priced generously in March beside the identical partner priced tightly in October, because two different people ran two different conversations. The quarterly pass that re-reads rules as classes is what keeps a growing agents array a policy rather than a pile of precedents.
Worked example: a parts catalogue with five rules and one lesson
Fictional example. Meridian Auto Parts, a fictional parts catalogue with 40,000 SKUs, publishes 5 rules. Two shopping agents get yes with browse, read, search, and shop on a paid tier at 60 requests per minute. A research agent gets yes for read, summarize, and quote, free, at 30 per minute, with data-use terms barring resale of its fitment data. One agent is set to no after it ignored the published rate limit for a month — the policy cannot punish it, but the refusal is now on the record. The catch-all is conditional at 10 per minute. The lesson arrived at the first edit: a well-meaning update pasted a second rule for the research agent instead of amending the first, and the validator rejected the file for a duplicate identifier. One agent, one rule — enforced by the checker, learned once.
The per-agent rule checklist
- One rule per identifier. Duplicates are a conformance error, never an override.
- One verdict per rule.
yes,no, orconditional— with terms that match the verdict. - Disjoint action lists. Nothing appears in both
permitted_actionsanddisallowed_actions. - Terms on every rule.
commercial_termsis required; add rate limits where load matters. - A catch-all with content. Give
generic/*real terms so strangers read conditions, not just a verdict.
Keep reading
Permitted vs Disallowed Actions in an Agent Policy · Rate Limits for AI Agents in agent-policy.json, Explained · Agent Access Policy Examples · Spec samples · Conformance · Pricing · All guides
Frequently asked questions
How many rules can a policy contain?
The spec sets no numeric limit. The samples use zero, one, and three rules. Practical limits are human: every rule is a decision someone must review when last_updated is refreshed, so most sites do well with a handful of named rules plus a catch-all.
Can two agents share one rule?
No. A rule names exactly one identifier, and each identifier may appear once. Agents that should receive the same answer each get their own identical rule — the format prefers explicit repetition over shared references an agent might misread.
What wins, a rule or the default?
The rule, for the agent it names. default_policy governs only agents with no matching rule. That is the layering the whole format rests on: a block default with one yes rule is a private arrangement with one agent, and an allow default with one no rule is an open site with one named refusal.
Does a no rule need disallowed_actions?
disallowed_actions is a required field on every rule, but a no rule may carry an empty permitted_actions list. Listing the disallowed actions anyway — as the blog sample does — makes the refusal explicit and self-documenting for the agent reading it.
Can a rule permit an action the vocabulary does not list?
Yes. The action vocabulary is non-exhaustive: owners may use other action names, and validators warn rather than fail on unknown actions. Use the suggested twelve where they fit, because agents already know those words, and invent new ones only where none fits.
Generate a policy — free · Validate a policy · What an agent access policy is