feat: Add support for guardrails

docs/docs/development/resource-architecture.md

@@ -45,12 +45,15 @@ The last two are not peers of the first four. Agent configuration is the leaf la
 | `rules.txt` | Global behavioral instructions |
 | `personality.yaml` | Tone and manner |
 | `role.yaml` | Who the agent is and what it is for |
+| `guardrails.yaml` | Checks that constrain what the agent can say or do |
 
 Rules are **always present in the prompt**, on every turn. They are not retrieved and not conditional, which makes them the right home for instructions that are unconditionally true — "always confirm the booking reference before making changes" — and the wrong home for facts, which would consume prompt space even when irrelevant to the current turn.
 
 `personality.yaml` and `role.yaml` are narrower than rules: they accept only `{{attr:}}` and `{{vrbl:}}` references. Behavioral references such as `{{fn:}}` and `{{ho:}}` belong in `rules.txt`.
 
-See [agent settings](../reference/resources/agent_settings.md).
+`guardrails.yaml` covers the same ground as rules from the other side. A rule is an instruction in the prompt, which the model can still be talked out of; a guardrail is a check evaluated against the conversation, with its own action when it trips. That makes them easy to confuse — "never give medical advice" is a plausible entry in either. Write it as a rule first, and add a guardrail when testing shows the rule alone isn't holding. The platform also ships a fixed catalog of guardrails you can only toggle, covering the failure modes no prompt reliably prevents on its own, such as jailbreak attempts.
+
+See [agent settings](../reference/resources/agent_settings.md) and [guardrails](../reference/resources/guardrails.md).
 
 ### Knowledge base
 
@@ -234,6 +237,7 @@ See [voice settings](../reference/resources/voice_settings.md), [chat settings](
 |---|---|
 | A new FAQ, policy, or factual answer | Topic (`topics/`) |
 | A global behavioral rule (always do X, never do Y) | `agent_settings/rules.txt` |
+| Enforcement for a rule the model keeps working around | Guardrail (`agent_settings/guardrails.yaml`) |
 | Agent identity and tone | `agent_settings/personality.yaml` and `role.yaml` |
 | A multi-step guided conversation | Flow (`flows/`) |
 | Structured data collection from the caller | Entity + flow |

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,142 @@
+---
+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, 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.
+
+It accepts every prefix in the [resource references table](../../development/resource-architecture.md#resource-references) except two: flow transition functions (`{{ft:...}}`) and entities (`{{entity:...}}`) fail validation in a guardrail action.
+
+### 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
+
+Validation 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 guardrail in the fixed catalog must be present in the file — none can be missing, though any can be `enabled: false`.
+- 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
+
+- 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,