Writing YAML policies for AI agents

YAML policies are the primary way to define what your AI agent can and cannot do. This guide covers patterns beyond the basics, showing how to handle real production scenarios.

Combining conditions

A rule can require multiple conditions to match. All conditions in a when block must be true for the rule to trigger:

- tool: "email.send"
  action: allow
  when:
    args.to:
      endsWith: "@yourcompany.com"
    args.attachments:
      equals: 0
  reason: "Internal emails without attachments are allowed"

Environment-specific policies

Use separate policy files for different environments:

policies/
  development.yaml   # Permissive, allows most actions
  staging.yaml       # Matches production rules, logs only
  production.yaml    # Strict, fail-closed

Load the right one based on your environment variable:

const guard = createGuard({
  policyPath: `./policies/${process.env.NODE_ENV}.yaml`
});

Time-based rules

Restrict actions to specific time windows using session context:

- tool: "deployment.trigger"
  action: block
  when:
    context.dayOfWeek:
      matches: "Saturday|Sunday"
  reason: "No deployments on weekends"

Escalation with metadata

Attach metadata to escalation rules so reviewers have context:

- tool: "payment.send"
  action: escalate
  when:
    args.amount:
      gt: 500
  reason: "Large payment requires CFO approval"
  metadata:
    approver_role: "cfo"
    sla_minutes: 30

Deny-by-default patterns

The safest pattern is to block everything and then allow specific tools:

rules:
  # Allowed tools (explicitly listed)
  - tool: "search.web"
    action: allow
  - tool: "file.read"
    action: allow
    when:
      args.path:
        startsWith: "/tmp/"
  - tool: "calculator.compute"
    action: allow

  # Everything else is blocked
  - tool: "*"
    action: block
    reason: "Tool not in allowlist"

Policy composition

For large deployments, split policies into modules and merge them:

import { mergePolices } from '@authensor/sdk';

const basePolicy = loadYaml('./policies/base.yaml');
const teamPolicy = loadYaml('./policies/team-finance.yaml');

const merged = mergePolicies(basePolicy, teamPolicy);
const guard = createGuard({ policy: merged });

Team-specific rules override base rules when they match the same tool pattern. This lets you maintain a shared security baseline while giving teams control over their own tool permissions.

Validating policies

Run the policy linter before deploying:

npx authensor policy lint ./policies/production.yaml

The linter checks for unreachable rules, conflicting conditions, missing reasons on escalation rules, and invalid regex patterns.