Agent Governance ToolkitAgent Governance Toolkit 4.1.0 · Python 3.10+
Dashboard
0%

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.

yaml
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: deny

Loading 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.

ExampleThe shop's tools governed by a YAML file
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}")

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-delete rule, 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, and matched_rule is None.

A policy in Python or a policy in a file

Policy in PythonPolicy in a YAML file
Lives inYour codeA file beside your code
Changed byEditing and redeploying codeEditing the file
Read byPolicyEngine / AgentKernelPolicyDocument / PolicyEvaluator
Reviewed asA code changeA 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.
Watch out. The context is a plain dictionary and the condition reads it by field name. The evaluator never calls your tools or reads their real arguments for you; you build the context dict and pass it in, so a field you forget to include is a field no rule can match on, which the Policy conditions and a missing field lesson takes apart.
Try it yourself
  • Add an allow-reply rule for the reply tool and confirm a reply is now allowed by name.
  • Change defaults.action to allow and watch escalate flip to allowed.
  • Print doc.name and len(doc.rules) to see what the file parsed into.

This is what real progress feels like.