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

Permissions that depend on the context

A conditional permission is a policy rule that allows a tool only when a field in the request's context says so, so the same call can be permitted for one caller and refused for another.

Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0

The Three YAML formats, and which one is real lesson settled which YAML dialect the loader reads. This part uses that loader to write rules that read the situation a call arrives in, not only the tool's name. The first situation is who is asking: the shop agent may issue a refund, but only when a manager is behind the request.

Loading a policy written inline

Every example in this part loads a short policy the same way. load writes the YAML to a temporary file and reads it back with from_yaml, the same loader a policy on disk uses, so each example stays self-contained.

python
import warnings; warnings.simplefilter("ignore")
import tempfile

from agent_os.policies.schema import PolicyDocument
from agent_os.policies.evaluator import PolicyEvaluator

def load(text):                                  # write the YAML to a file, then load it back
    f = tempfile.NamedTemporaryFile("w", suffix=".yaml", delete=False)
    f.write(text)
    f.close()
    return PolicyDocument.from_yaml(f.name)

A rule that reads the caller's role

A condition is one {field, operator, value} triple. This policy has two rules: one allows the refund at priority 10 when the role field equals manager, and a default-priority rule denies the refund tool outright. A manager's request matches both, and the higher priority wins; everyone else matches only the deny.

python
POLICY = """
version: "1.0"
name: refund-by-role
# a manager may refund; any other role is denied the refund tool
rules:
  - name: manager-may-refund
    condition: {field: role, operator: eq, value: manager}
    action: allow
    priority: 10

  - name: refund-needs-a-manager
    condition: {field: tool, operator: eq, value: refund}
    action: deny
"""

The same refund, two contexts

Build the evaluator from the loaded document and call evaluate with a context dict. The only thing that changes between the two calls is the role field, and the verdict changes with it.

ExampleOne refund, allowed for a manager and denied for an agent
doc = load(POLICY)
evaluator = PolicyEvaluator(policies=[doc])

# the same refund, asked once as a manager and once as an agent
for role in ["manager", "agent"]:
    d = evaluator.evaluate({"tool": "refund", "role": role})
    print(f"{role:8} allowed={d.allowed}  action={d.action}  rule={d.matched_rule}")

What the context decided

  • The manager's refund was allowed by manager-may-refund, because its role condition matched and its priority of 10 beat the default-priority deny rule.
  • The agent's refund was denied by refund-needs-a-manager: the role condition did not match, so only the deny rule was left.
  • The tool name never changed. Both calls were a refund; the context field decided the outcome, which is the whole point of a conditional permission.

A permission on the name alone, or on the context

A permission on the tool nameA conditional permission
Decides fromThe tool name onlyA field in the request context
Same tool, two callersSame verdict for bothCan allow one and deny the other
Where it livesAn allow-list of namesA rule with a condition

Where you use a conditional permission

  • A tool only some roles may run, such as a refund a manager approves but a front-line agent cannot.
  • A tenant or environment check, so the same tool is allowed in staging and denied in production.
  • A per-customer limit, where a field on the request marks an account the action is or is not allowed against.
Watch out. A condition whose field is absent from the context does not match, so a rule guarding a tool is silently skipped when the request forgets to carry its field. Make the agent always set role, and keep a low-priority deny as the backstop, the way this policy does.
Try it yourself
  • Add a role: admin case and give admin its own allow rule at priority 20.
  • Remove the role field from one context and watch the deny rule catch it.
  • Give refund-needs-a-manager a priority of 20 and watch it deny even a manager.

Every expert started right here.