Writing a policy in a YAML file
A policy file is a YAML document that holds the same allow and deny decisions you wrote in Python, so the rules live in a file you can read, review and ship without touching the code.
Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0
The Two ways the engine checks a call lesson kept every rule inside Python. This part moves them into a file. A PolicyDocument loads the file, and a PolicyEvaluator reads a plain context dictionary against it, so the same shop agent is governed by a document anyone on the team can open.
Writing the shop policy
Syntax: a policy file has a name, a list of rules, and a defaults block. Each rule has a name, a condition that reads one field of the context, and an action. This file allows the two safe tools, denies the account deletion, and defaults to deny.
version: "1.0"
name: shop-policy
rules:
- name: allow-status
condition: {field: action, operator: eq, value: order_status}
action: allow
- name: allow-refund
condition: {field: action, operator: eq, value: refund}
action: allow
- name: block-delete
condition: {field: action, operator: eq, value: delete_account}
action: deny
defaults:
action: denyLoading the file and evaluating the agent's tools
PolicyDocument.from_yaml reads the file and PolicyEvaluator evaluates a context against it. The context is a plain dictionary; here it carries the action the shop agent chose, and the evaluator returns a decision with allowed and the rule that matched.
import warnings; warnings.simplefilter("ignore") # hush the deprecation warning
from agent_os.policies.schema import PolicyDocument
from agent_os.policies.evaluator import PolicyEvaluator
doc = PolicyDocument.from_yaml("shop.yaml") # the file shown above
check = PolicyEvaluator(policies=[doc])
# ask the file about each tool the shop agent might choose
for action in ["order_status", "refund", "delete_account", "escalate"]:
d = check.evaluate({"action": action})
print(f"{action:16} allowed={d.allowed!s:5} rule={d.matched_rule}")order_status allowed=True rule=allow-status refund allowed=True rule=allow-refund delete_account allowed=False rule=block-delete escalate allowed=False rule=None
What the decisions say
- order_status and refund were allowed, each matched by the allow rule whose name the decision reports, so you can see which rule let the call through.
- delete_account was denied by the
block-deleterule, the same refusal the Python engine gave, now written in a file. - escalate matched no rule, so the decision fell through to
defaults.action, which is deny, andmatched_ruleisNone.
A policy in Python or a policy in a file
| Policy in Python | Policy in a YAML file | |
|---|---|---|
| Lives in | Your code | A file beside your code |
| Changed by | Editing and redeploying code | Editing the file |
| Read by | PolicyEngine / AgentKernel | PolicyDocument / PolicyEvaluator |
| Reviewed as | A code change | A document a non-coder can read |
Where you use a policy file
- A policy a non-coder has to approve, where a reviewer reads the rules without reading Python.
- A rule set that changes more often than the code, so a new deny ships as a file edit.
- Several deployments that share one rule set, each loading the same file.
Related
- Previous: Two ways the engine checks a call
- Next: Policy conditions and a missing field
- See also: Allow-lists and default deny
- Reference: Agent Governance Toolkit documentation
- Add an
allow-replyrule for thereplytool and confirm a reply is now allowed by name. - Change
defaults.actiontoallowand watchescalateflip to allowed. - Print
doc.nameandlen(doc.rules)to see what the file parsed into.
This is what real progress feels like.