Skip to main content
A purpose policy is the rule that decides what happens when an agent declares a purpose: allow, deny, route to a human approver, or shadow-evaluate without taking action. This guide walks through the compose / test / approve workflow that pairs with Define your first purpose.
Defining a purpose creates the what (the elements an agent is allowed to touch). Defining a policy creates the how (when the match counts, who has to approve, what TTL the token gets).

​
1. Compose the policy

App dashboard → Policies → New policy. Pick the purpose you want to gate and fill the form: 
policy_id: support_lookup_business_hours
purpose_id: customer_support_lookup
match:
  identity_required: true
  user_groups: ["support-tier-1", "support-tier-2"]
  data_source_id: salesforce_prod
decision: allow
token_ttl_minutes: 5
approval_required: false
shadow_mode: true
Every field except purpose_id and decision is optional. Defaults are conservative — if you forget to set identity_required, the policy will not match any anonymous traffic.

​
2. Test in shadow mode

shadow_mode: true means the policy evaluates on every matching tool call but does not affect the outcome. The decision feed shows what would have happened. Watch for one to two weeks. The dashboard surfaces three numbers per shadow policy:
  • Match rate — % of qualifying traffic the policy fires on
  • Would-deny rate — fraction of matches that would have been blocked
  • Confidence drift — how often the intent classifier was uncertain
If would-deny is above 5% on intended traffic, refine the match rule before promoting.

​
3. Route through approval (optional)

For high-risk purposes (PII export, admin write), set approval_required: true. The policy queues the call into Slack + email. Approvers see the full intent context and can grant, deny, or delegate.

​
4. Promote to live

Toggle shadow_mode: false (one click in the UI). The next matching tool call gets a real allow / deny / approval decision written to the audit log. Promotion is reversible — if something looks wrong, flip back to shadow within 30 seconds.