Policies
A Policy is a deterministic rule that runs at a fixed hook point of a Call, such as on_tool_call or before_speak, and outputs one action type: it can block, transfer, end, redact, tag or steer what the Agent does. Its logic is a JSON Decision Model document that the rules engine evaluates against the Call context of its hook. A Policy with no match does nothing.
On the Phase 0 host. Served: every Policy route since contracts 1.47.0, and Policies in Calls since 1.48.0.
The lifecycle
| Step | Operation |
|---|---|
| Create a draft; the document is linted at its hook and for its action type | POST /v1/policies |
| Change the draft at its revision | PATCH /v1/policies/{policy_id} |
| Dry-run the draft or a version against a synthetic context | POST /v1/policies/{policy_id}/evaluate |
| Publish the draft as the next version, optionally activating it | POST /v1/policies/{policy_id}/versions |
| Activate a version, which is also how you roll back | POST /v1/policies/{policy_id}/versions/{version}/activate |
| Archive the Policy; pinned versions keep running | DELETE /v1/policies/{policy_id} |
A save or a publish with an error finding is refused with one 422 validation_failed that names each node and code; warnings never refuse and come back in analysis.warnings. The reserved action types set_setting and record_opt_out are refused with capability_not_available. A dry run writes nothing: no Call event, Audit event or Usage event.
How a Policy reaches a Call
- Agent scope. Attach the Policy with
policy_idson the Agent draft. Publishing the Agent version pins the active version of each, so a new Policy version reaches Calls through the next Agent version publish. - Organization scope. The Policy runs on every Call of the Organization, resolved to its active version when each Call is admitted. Writing one needs
policies:adminbesidespolicies:write. - A Call never changes Policy versions while it runs. The
enabledswitch on a Policy is read when a Call is dispatched, so turning it off takes effect from the next Call without a publish.
POST /v1/agents/{agent_id}/versions/{version}/evaluate-policies dry-runs the whole set of an Agent version at one hook, in the order Calls run it: by priority, then organization scope before agent scope.
What a firing leaves behind
Each firing is a Call event, policy.fired, policy.timeout or policy.error, with the Policy id, its version, the hook and the action; read them on the Call's events or live on the events channel. Publishing and activating name the Webhook events policy.version.published and policy.version.activated. Delivery to an endpoint of yours takes a Webhook subscription, whose operations contracts 1.63.0 adds (Webhooks); each of their pages says whether the Phase 0 host serves it.