feat: Add support for guardrails

docs/docs/reference/resources.md

@@ -16,6 +16,7 @@ Every resource here follows the same sync process, including [permission-gated v
 | Resource | Configures | File |
 |---|---|---|
 | [Agent settings](./resources/agent_settings.md) | Personality, role, and global rules | `agent_settings/` |
+| [Guardrails](./resources/guardrails.md) | Platform and custom checks that constrain agent behavior | `agent_settings/guardrails.yaml` |
 | [Languages](./resources/languages.md) | Supported languages for a multilingual agent | `agent_settings/languages.yaml` |
 | [Experimental config](./resources/experimental_config.md) | Opt-in experimental platform features | `agent_settings/experimental_config.json` |
 

docs/docs/reference/resources/agent_settings.md

@@ -25,6 +25,7 @@ agent_settings/
 ├── personality.yaml
 ├── role.yaml
 ├── rules.txt
+├── guardrails.yaml                 # Optional
 ├── safety_filters.yaml             # Optional
 └── experimental_config.json        # Optional
 ~~~
@@ -51,6 +52,12 @@ agent_settings/
 
     Provides plain-text instructions the agent should follow on every turn.
 
+-   **Guardrails**
+
+    ---
+
+    Platform and custom checks that constrain agent behavior at runtime.
+
 -   **Languages**
 
     ---
@@ -215,6 +222,12 @@ That kind of logic belongs in flows and Python functions.
 - concise instructions that apply broadly
 - deterministic logic handled in code or flow transitions
 
+## Guardrails
+
+The optional `guardrails.yaml` file configures platform and custom guardrails — runtime checks that constrain what the agent can say or do.
+
+See the [Guardrails reference](./guardrails.md) for full field descriptions, validation rules, and examples.
+
 ## Languages
 
 The optional `languages.yaml` file configures which languages the agent supports. When present, it defines the default language and any additional languages.
@@ -245,6 +258,13 @@ See the [Safety filters reference](./safety_filters.md) for field descriptions,
     Learn how referenced global functions are defined and used.
     [Open functions](./functions.md)
 
+-   **Guardrails**
+
+    ---
+
+    Configure platform and custom guardrails that constrain agent behavior.
+    [Open guardrails](./guardrails.md)
+
 -   **Languages**
 
     ---

docs/docs/reference/resources/guardrails.md

@@ -0,0 +1,151 @@
+---
+title: Guardrails
+description: Configure platform and custom guardrails that constrain agent behavior during a conversation.
+---
+
+# Guardrails
+
+<p class="lead">
+Guardrails are runtime checks that constrain what the agent can say or do, catching problems a prompt or rule alone can't reliably prevent.
+</p>
+
+There are two kinds: a fixed catalog of **platform guardrails** you can only toggle on or off, and **custom guardrails** you define yourself with a trigger condition and an action.
+
+## Location
+
+Both kinds of guardrail live in a single optional file:
+
+~~~text
+agent_settings/
+└── guardrails.yaml       # Optional
+~~~
+
+## What guardrails control
+
+<div class="grid cards" markdown>
+
+-   **Platform guardrails**
+
+    ---
+
+    A fixed set of platform-provided checks. Only the `enabled` toggle can be changed.
+
+-   **Custom guardrails**
+
+    ---
+
+    Your own rules: a prompt describing when the guardrail should trigger, and an action describing what happens when it does.
+
+</div>
+
+## Platform guardrails
+
+!!! note "Fixed catalog — enable or disable only"
+    The catalog of platform guardrails is fixed by the platform. You can enable or disable each one with `poly push`, but you cannot create a new platform guardrail or delete an existing one via the ADK.
+
+### The catalog
+
+| Name | Description |
+|---|---|
+| `ai_identity` | Has the agent disclose that it's an AI when asked. |
+| `emergency_escalation` | Detects emergencies and escalates instead of continuing the conversation normally. |
+| `hallucination_control` | Reduces factually unsupported or made-up responses. |
+| `jailbreak_defence` | Detects and blocks attempts to override the agent's instructions or persona. |
+| `tool_call_integrity` | Checks that the agent's function/tool calls are well-formed and intended. |
+
+### Fields
+
+| Field | Description |
+|---|---|
+| `name` | One of the fixed catalog names above. |
+| `enabled` | `true` or `false`. Default: `true`. |
+
+### Example
+
+~~~yaml
+platform_guardrails:
+  - name: jailbreak_defence
+    enabled: true
+  - name: hallucination_control
+    enabled: false
+~~~
+
+## Custom guardrails
+
+Custom guardrails live under an optional `custom_guardrails` list in the same file. Unlike platform guardrails, they can be created, updated, and deleted via the ADK.
+
+### Fields
+
+| Field | Description |
+|---|---|
+| `name` | Display name for the guardrail. |
+| `prompt` | Describes the condition that triggers the guardrail. Free text — references are not evaluated here. |
+| `action` | Describes what the agent should do when the guardrail triggers, for example `warn`, or an instruction that calls a function, handoff, or SMS template. |
+| `enabled` | `true` or `false`. Default: `true`. |
+
+### Supported references in `action`
+
+`action` is the only field scanned for references — a reference written in `prompt` is treated as plain text.
+
+| Syntax | Meaning |
+|---|---|
+| `{{fn:function_name}}` | [Global function](./functions.md) |
+| `{{twilio_sms:template_name}}` | [SMS template](./sms.md) |
+| `{{ho:handoff_name}}` | [Handoff](./handoffs.md) |
+| `{{attr:attribute_name}}` | [Variant attribute](./variants.md) |
+| `{{vrbl:variable_name}}` | [State variable](./variables.md) |
+| `{{tn:translation_key}}` | [Translation](./translations.md) |
+
+Flow transition functions (`{{ft:...}}`) and entity references (`{{entity:...}}`) are not supported in a guardrail action and fail validation.
+
+### Example
+
+~~~yaml
+custom_guardrails:
+  - name: No medical advice
+    enabled: true
+    action: warn
+    prompt: Never give medical advice. Offer to transfer the caller to a human instead.
+~~~
+
+## Validation
+
+`poly push` rejects a `guardrails.yaml` that doesn't satisfy these rules:
+
+- Every platform guardrail's `name` must be one of the fixed catalog names; anything else is rejected with the list of valid names.
+- Every platform and custom guardrail's `enabled` must be a boolean (`true`/`false`, unquoted).
+- A custom guardrail's `name`, `prompt`, and `action` are all required.
+- Any `{{prefix:name}}` reference in a custom guardrail's `action` must use one of the supported prefixes above, and must resolve to a resource that actually exists.
+
+## Best practices
+
+- Only add a custom guardrail for behavior a rule or prompt instruction hasn't reliably caught in testing — they add latency to every turn.
+- Keep `prompt` focused on the trigger condition and `action` focused on the response; don't fold both into one field.
+- Disable a platform or custom guardrail with `enabled: false` instead of deleting it, so it's easy to re-enable later.
+
+## Related pages
+
+<div class="grid cards" markdown>
+
+-   **Safety filters**
+
+    ---
+
+    Content filtering on user input and agent output, configured per channel.
+    [Open safety filters](./safety_filters.md)
+
+-   **Agent settings**
+
+    ---
+
+    Personality, role, and rules — the other resources that shape agent behavior.
+    [Open agent settings](./agent_settings.md)
+
+-   **Functions**
+
+    ---
+
+    Global functions that a custom guardrail's action can call.
+    [Open functions](./functions.md)
+
+</div>

docs/docs/reference/resources/safety_filters.md

@@ -185,6 +185,13 @@ The same settings can be configured in the Agent Studio UI. The platform docs co
     Configure personality, role, and rules alongside project-level safety filters.
     [Open agent settings](./agent_settings.md)
 
+-   **Guardrails**
+
+    ---
+
+    Runtime checks that constrain agent behavior, rather than filtering content.
+    [Open guardrails](./guardrails.md)
+
 -   **Voice settings**
 
     ---

docs/mkdocs.yml

@@ -142,6 +142,7 @@ nav:
       - Resource reference:
           - Overview: reference/resources.md
           - Agent settings: reference/resources/agent_settings.md
+          - Guardrails: reference/resources/guardrails.md
           - Topics: reference/resources/topics.md
           - Functions: reference/resources/functions.md
           - Flows: reference/resources/flows.md

src/poly/resources/__init__.py

@@ -41,6 +41,7 @@
     FunctionParameters,
     FunctionType,
 )
+from poly.resources.guardrails import CustomGuardrail, PlatformGuardrail
 from poly.resources.handoff import (
     Handoff,
     HandoffSipConfig,