Skip to Content
ConceptsPolicy Engine

Policy Engine

Condition-based authorization rules that integrate with Guardian action checks.

Overview

The policy engine evaluates organization-defined rules to make allow/deny decisions for agent actions. Policies are evaluated by priority (highest first), and the first matching policy wins. If no policy matches, the decision is no_match (defers to default Guardian behavior).

How It Works

Policy engine evaluation flow An Agent Action Request loads policies sorted by priority descending with a 5-minute cache per org, then evaluates each policy where all conditions must match. A matching allow rule returns ALLOW; a matching deny rule returns DENY; with no match the engine continues to default Guardian behavior. Agent Action Request Load Policies sorted by priority desc 5-minute cache per org Evaluate Each Policy all conditions must match first match wins ALLOW match (allow) DENY match (deny) no match - continue defers to Guardian match (allow) match (deny) no match (continue)

Rule Schema

{
  "name": "Allow web search for trusted agents",
  "policy_type": "tool",
  "rules": {
    "effect": "allow",
    "priority": 100,
    "conditions": {
      "tool_name": {"in": ["web_search", "news_search"]},
      "reputation_score": {"gte": 0.7}
    }
  }
}
FieldTypeDescription
effectstring"allow" or "deny"
priorityintHigher values are evaluated first
conditionsobjectMap of field name to condition matcher

Condition Fields

FieldValue TypeDescription
tool_namestringName of the tool being invoked
agent.entity_typestringAgent type: ai_agent, human
source_protocolstringProtocol: a2a, mcp, api
reputation_scorefloat64Agent’s reputation score (0.0-1.0)
agent.capabilities[]stringAgent’s registered capabilities

AgentTrust ID 1.0 Condition Fields

These fields were added in AgentTrust ID 1.0 for session-aware and effect-aware policy evaluation.

FieldValue TypeDescription
action_namestringPreferred over tool_name (same value, clearer name for AgentTrust ID)
action_effectstringDeclared effect of the action: read, mutating, destructive, admin
session_modestringCurrent session mode: read_only, scoped, elevated
delegation_depthnumericDelegation chain depth: 0 = direct, 1+ = delegated

These fields use the same condition matchers as all other fields. For example, to deny destructive actions in read-only sessions:

{
  "name": "Deny destructive actions in read-only sessions",
  "policy_type": "tool",
  "rules": {
    "effect": "deny",
    "priority": 300,
    "conditions": {
      "action_effect": {"in": ["destructive", "admin"]},
      "session_mode": {"eq": "read_only"}
    }
  }
}

Condition Matchers

MatcherTypeDescription
in[]stringValue must be in the list
not_in[]stringValue must not be in the list
eqstringExact string match
containsstringArray field must contain this value
gtefloat64Numeric value >= threshold
ltefloat64Numeric value <= threshold

Multiple conditions in a single rule are AND-ed (all must match).

Evaluation Decision

The engine returns a Decision object after evaluating policies:

{
  "effect": "allow",
  "policy_id": "matched-policy-uuid",
  "reason": "matched policy \"Allow web search for high-trust agents\""
}
FieldTypeDescription
effectstring"allow", "deny", or "no_match" (no policy matched)
policy_idstringID of the matched policy (omitted when effect is "no_match")
reasonstringHuman-readable explanation of the decision

When effect is "no_match", no policy applied and the decision defers to default Guardian behavior.

API Reference

POST /api/v1/policies — Create Policy

Status: 201 Created

curl -X POST http://localhost:8080/api/v1/policies \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Allow web search for trusted agents",
    "policy_type": "tool",
    "rules": {
      "effect": "allow",
      "priority": 100,
      "conditions": {
        "tool_name": {"in": ["web_search"]},
        "reputation_score": {"gte": 0.7}
      }
    },
    "metadata": {"owner": "security-team", "ticket": "SEC-123"}
  }'
FieldTypeRequiredDescription
namestringYesPolicy name (max 255 characters)
policy_typestringYes"agent", "tool", or "delegation"
rulesobjectYesRule definition (effect, priority, conditions)
metadataobjectNoArbitrary key-value metadata

GET /api/v1/policies — List Policies

Status: 200 OK

curl http://localhost:8080/api/v1/policies \
  -H "Authorization: Bearer sk_live_..."

Response:

{
  "policies": [
    {
      "id": "policy-uuid",
      "org_id": "org-uuid",
      "name": "Allow web search for trusted agents",
      "policy_type": "tool",
      "rules": {"effect": "allow", "priority": 100, "conditions": {"..."}},
      "enabled": true,
      "created_at": "2026-03-01T00:00:00Z",
      "updated_at": "2026-03-01T00:00:00Z",
      "created_by": "user-uuid",
      "metadata": {"owner": "security-team"}
    }
  ],
  "total": 1
}

PUT /api/v1/policies/{policyID} — Update Policy

Status: 200 OK

Partial updates supported. Only include fields you want to change.

curl -X PUT http://localhost:8080/api/v1/policies/policy-uuid \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Returns the full updated policy object.

DELETE /api/v1/policies/{policyID} — Delete Policy

Status: 200 OK

curl -X DELETE http://localhost:8080/api/v1/policies/policy-uuid \
  -H "Authorization: Bearer sk_live_..."

Response:

{
  "deleted": true,
  "policy_id": "policy-uuid"
}

Example Policies

Allow web search for high-trust agents

{
  "name": "Allow web search for high-trust agents",
  "policy_type": "tool",
  "rules": {
    "effect": "allow",
    "priority": 100,
    "conditions": {
      "tool_name": {"in": ["web_search", "news_search"]},
      "reputation_score": {"gte": 0.7}
    }
  }
}

Deny dangerous tools for AI agents

{
  "name": "Block dangerous tools for AI agents",
  "policy_type": "tool",
  "rules": {
    "effect": "deny",
    "priority": 200,
    "conditions": {
      "tool_name": {"in": ["shell_exec", "file_delete", "network_scan"]},
      "agent.entity_type": {"eq": "ai_agent"}
    }
  }
}

Block low-reputation agents from delegation

{
  "name": "Deny delegation for untrusted agents",
  "policy_type": "delegation",
  "rules": {
    "effect": "deny",
    "priority": 100,
    "conditions": {
      "reputation_score": {"lte": 0.3}
    }
  }
}

Deny admin actions beyond delegation depth 1

{
  "name": "Deny admin actions for deeply delegated agents",
  "policy_type": "tool",
  "rules": {
    "effect": "deny",
    "priority": 250,
    "conditions": {
      "action_effect": {"eq": "admin"},
      "delegation_depth": {"gte": 2}
    }
  }
}

Require elevated session for mutating actions

{
  "name": "Deny mutating actions outside elevated sessions",
  "policy_type": "tool",
  "rules": {
    "effect": "deny",
    "priority": 200,
    "conditions": {
      "action_effect": {"in": ["mutating", "destructive", "admin"]},
      "session_mode": {"in": ["read_only", "scoped"]}
    }
  }
}

Caching

Policies are cached per organization using two complementary strategies:

  1. TTL-based expiry — Each org’s policy set is cached in memory with a 5-minute TTL. After expiry, the next evaluation reloads policies from the database.
  2. Explicit invalidation — Create, update, and delete operations immediately call InvalidateCache(orgID), removing the org’s cached entries so the next evaluation loads fresh data.

This means policy changes take effect immediately for the affected organization (no stale-cache window), while read-heavy evaluation workloads avoid repeated database queries.

Last updated on
Authorization ModelDelegation Chains