Policies

Governance controls that evaluate every request before it reaches a provider.

Overview

Policies are rules that control how AI agents can operate. They're evaluated before every request and can allow, deny, warn, or require approval.

Policy Types

Type	Description
`budget.per_day`	Daily spending limit in USD
`budget.per_month`	Monthly spending limit in USD
`budget.per_request`	Maximum cost per individual request
`model.allowlist`	Only allow specific models
`model.blocklist`	Block specific models
`rate_limit`	Requests per minute/hour limit
`approval_required`	Require human approval before execution

Creating a Policy

1curl -X POST http://localhost:3001/v1/policies \
2  -H "Content-Type: application/json" \
3  -d '{
4    "name": "Daily Budget Cap",
5    "type": "budget.per_day",
6    "enabled": true,
7    "priority": 10,
8    "scope": {
9      "type": "workspace",
10      "id": "ws_123"
11    },
12    "action": {
13      "type": "deny",
14      "parameters": {
15        "limit_usd": 50
16      }
17    }
18  }'

Policy Scopes

Policies can apply at different levels:

workspace — Applies to all agents in a workspace
team — Applies to agents belonging to a team
agent — Applies to a specific agent only

1// Workspace-level policy
2{
3  "scope": { "type": "workspace", "id": "ws_123" }
4}
5
6// Team-level policy (inherits workspace, adds restrictions)
7{
8  "scope": { "type": "team", "id": "team_engineering" }
9}
10
11// Agent-level policy (most specific)
12{
13  "scope": { "type": "agent", "id": "agent_support_bot" }
14}

Policy Actions

deny — Block the request immediately
warn — Allow but log a warning, alert operators
require_approval — Queue for human approval

Priority and Evaluation Order

Policies are evaluated in priority order (lower number = higher priority):

1// Priority 1: Check model allowlist first
2{ "priority": 1, "type": "model.allowlist" }
3
4// Priority 10: Then check budget
5{ "priority": 10, "type": "budget.per_day" }
6
7// Priority 100: Rate limits checked last
8{ "priority": 100, "type": "rate_limit" }
9
10// If any policy denies, request is blocked

Example Policies

Budget Management

1// $100/day budget with warning at 80%
2{
3  "name": "Daily Budget",
4  "type": "budget.per_day",
5  "action": {
6    "type": "deny",
7    "parameters": {
8      "limit_usd": 100,
9      "warn_at_percent": 80
10    }
11  }
12}
13
14// Max $5 per request
15{
16  "name": "Request Cap",
17  "type": "budget.per_request",
18  "action": {
19    "type": "deny",
20    "parameters": {
21      "limit_usd": 5
22    }
23  }
24}

Model Restrictions

1// Only allow specific models
2{
3  "name": "Approved Models Only",
4  "type": "model.allowlist",
5  "action": {
6    "type": "deny",
7    "parameters": {
8      "models": [
9        "claude-3-5-sonnet",
10        "gpt-4o",
11        "gpt-4o-mini"
12      ]
13    }
14  }
15}
16
17// Block expensive models for non-critical agents
18{
19  "name": "Block GPT-4",
20  "type": "model.blocklist",
21  "scope": { "type": "agent", "id": "agent_demo_bot" },
22  "action": {
23    "type": "deny",
24    "parameters": {
25      "models": ["gpt-4", "gpt-4-32k"]
26    }
27  }
28}

Approval Gates

1// Require approval for expensive requests
2{
3  "name": "High Cost Approval",
4  "type": "approval_required",
5  "action": {
6    "type": "require_approval",
7    "parameters": {
8      "conditions": [
9        { "field": "estimated_cost_usd", "operator": "gt", "value": 10 }
10      ],
11      "approvers": ["admin@company.com"],
12      "timeout_hours": 24
13    }
14  }
15}

Policy Simulation

Test how policies will evaluate without making a real request:

1curl -X POST http://localhost:3001/v1/policies/evaluate \
2  -H "Content-Type: application/json" \
3  -d '{
4    "workspace_id": "ws_123",
5    "agent_id": "agent_456",
6    "model": "gpt-4",
7    "estimated_cost_usd": 15.00
8  }'
9
10# Response:
11{
12  "allowed": false,
13  "evaluated_policies": [
14    { "policy_id": "pol_model_allowlist", "result": "failed", "reason": "gpt-4 not in allowlist" }
15  ],
16  "blocking_policy": { "name": "Approved Models Only", "type": "model.allowlist" }
17}

Use simulation to test policy changes before deploying them. Great for CI/CD pipelines.