Skip to main content
Policies are the guardrails that keep your assistants safe and on-brand. Each policy runs a check at a specific enforcement point in a turn and takes an action when the check fails — for example, blocking a response, redacting sensitive text, or pausing for human approval. Like assistants and tools, policies use a revision model: a Policy record holds identity and a pointer to the active PolicyRevision, which holds the check and action configuration. Make a revision live with POST /v1/policies/{policy_id}/set-active-revision.

​
Enforcement points

A policy declares where in the turn it runs: Pin a pre_tool or post_tool policy to a specific tool with tool_target (a canonical tool key such as api:<uuid>).

​
Check types

Each policy revision uses one of two check types:

expression

A deterministic rule evaluated against turn context (message text, tool arguments, tool results). Fast and free. Inspect the available paths and operators with GET /v1/policies/expression-schema.

llm_judge

A natural-language rubric (guardrail_text) evaluated by a judge model. Use it for nuanced checks like tone, compliance, or topicality. Configure the org-wide judge model with GET/PUT /v1/policies/judge-model.

​
Actions

When a check fails, the policy takes its configured action: Configure the action with action_config — for example a safe_message for block or disclaimer_text for append.

​
Enforce vs. monitor

Every policy revision has a mode that controls whether it acts or just observes:

monitor

The default. The policy evaluates and records what it would have done (would_be_action) but never changes the conversation. Use it to canary a new policy safely.

enforce

The policy takes its action for real.
Two more dials tune behavior:
  • strictness — strict or relaxed (default relaxed). Trades latency for thoroughness on streaming responses.
  • on_error — fail_open or fail_closed. Whether a check that errors lets the turn proceed or blocks it. block policies default to fail_closed.

​
Organization-wide policies and the kill switch

A policy’s scope (set at creation) controls how it attaches:
  • attachable (default) — opt-in; you attach it to specific assistant revisions.
  • organization — automatically applies to every assistant in the org; never appears in policy_refs.
There is also an org-wide master switch: GET/PUT /v1/policies/enforcement. Turning enforcement off makes the resolver yield no policies for the entire organization — useful as an emergency kill switch.

​
Attaching policies to an assistant

Attach attachable policies to an assistant revision with PUT /v1/assistants/revisions/{revision_id}/policies:
policy_refs is a full replacement of the attachment set ([] detaches all). policies_enabled is a per-revision master switch. Preview how everything resolves — per enforcement point, per transport — with GET /v1/assistants/{agent_id}/enforcement-plan.
Evaluation priority is set by the priority field on the policy revision, not on the attachment. An attachment reference carries only policy_id.

​
Inspecting evaluations

Every policy evaluation is recorded. Query the audit log with GET /v1/policies/evaluations, filtering by conversation_id, policy_id, result, or enforcement_point. Each row includes result (pass, fail, error, or skipped), action_taken, would_be_action, mode, transport_class, channel, and latency_ms.

​
Next steps

Human-in-the-loop

See how the require_approval and handoff actions surface to human reviewers.

Policies API reference

Full reference for policy, revision, enforcement, and evaluation endpoints.