# Policies

## Overview

Policies are structured prompts that define agent behavior rules. Each policy specifies a condition to detect, an action to take, and optionally a criticality level and tool references.

Policies are stored as text prompts on the platform. The SDK parses the YAML or JSON content into typed Python objects.

***

## Convenience methods

These methods automatically apply the folder prefix and `type="policy"`, so you don't have to.

## `get_policy` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3494)

Get a policy prompt by name.

Automatically prefixes the name with `policies/` and sets `type="policy"`.

```python
get_policy(
    name: str,
    *,
    version: int | None = None,
    label: str | None = None,
    cache_ttl_seconds: int | None = None,
    fallback: str | None = None,
    max_retries: int | None = None,
    fetch_timeout_seconds: int | None = None,
) -> PolicyPromptClient
```

**Parameters**

* `name` — Policy name (without the `policies/` prefix).
* `version` — Optional version number.
* `label` — Optional label filter.
* `cache_ttl_seconds` — Cache TTL override.
* `fallback` — Fallback YAML/JSON content string.
* `max_retries` — Maximum number of retries.
* `fetch_timeout_seconds` — Fetch timeout override.

**Returns**

PolicyPromptClient

***

## `create_policy` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3532)

Create a policy prompt.

Automatically prefixes the name with `policies/` and sets `type="policy"`.

```python
create_policy(
    *,
    name: str,
    prompt: str,
    labels: List[str] | None = None,
    tags: List[str] | None = None,
    config: Any | None = None,
    commit_message: str | None = None,
) -> PolicyPromptClient
```

**Parameters**

* `name` — Policy name (without the `policies/` prefix).
* `prompt` — YAML or JSON content string.
* `labels` — Labels to assign.
* `tags` — Tags to assign.
* `config` — Additional config dict.
* `commit_message` — Optional commit message.

**Returns**

PolicyPromptClient

***

## `update_policy` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3567)

Update a policy prompt version.

Automatically sets `type="policy"` and routes through the type-specific endpoint.

```python
update_policy(
    *,
    name: str,
    version: int,
    new_labels: List[str] | None = None,
) -> Any
```

**Parameters**

* `name` — Policy name (without the `policies/` prefix).
* `version` — The version number of the prompt to update.
* `new_labels` — New labels to assign to the prompt version.

**Returns**

The updated prompt from the InteractiveAI API.

***

## `list_policies` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3591)

List policy prompts.

```python
list_policies(
    *,
    label: str | None = None,
    tag: str | None = None,
    page: int | None = None,
    limit: int | None = None,
) -> PromptMetaListResponse
```

**Parameters**

* `label` — Optional label filter.
* `tag` — Optional tag filter.
* `page` — Page number.
* `limit` — Items per page.

**Returns**

PromptMetaListResponse

***

## `delete_policy` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3612)

Delete a policy prompt.

Automatically prefixes the name with `policies/`.

```python
delete_policy(
    name: str,
    *,
    label: str | None = None,
    version: int | None = None,
) -> None
```

**Parameters**

* `name` — Policy name (without the `policies/` prefix).
* `label` — If set, deletes versions carrying this label.
* `version` — If set, deletes only this specific version.

***

## Fetching policies

```python
policies = client.get_policy("handoff-rules")

for g in policies.entries:
    print(g.id, g.criticality, g.action)
```

***

## Creating policies

```python
content = """
policies:
  - id: handoff_policy
    criticality: HIGH
    condition: "The user is abusive or requests a human agent"
    description: "Detect aggressiveness or explicit desire to speak to a human."
    action: "Use the initiate_human_handoff tool to transfer the conversation."
    tools:
      - initiate_human_handoff
    prioritize_over:
      - goodbye_policy

  - id: goodbye_policy
    criticality: HIGH
    condition: "The customer says goodbye"
    description: "Handle farewell."
    action: "Wish the customer a good day and call close_conversation."
    tools:
      - close_conversation
"""

policies = client.create_policy(
    name="handoff-rules",
    prompt=content,
    labels=["production"],
)
```

The SDK validates the YAML structure on create and raises `ValueError` if the content is malformed.

***

## `PolicyPromptClient`

Returned by `get_policy()` and `create_policy()`.

**Attributes**

* `name` — Prompt name.
* `version` — Prompt version number.
* `labels` — List of labels (e.g. `["production"]`).
* `tags` — List of tags.
* `config` — Arbitrary config dict stored with the prompt.
* `is_fallback` — `True` if this was returned from a fallback value.
* `raw_content` — The original unparsed text content.
* `entries` — `List[PolicyEntry]` (property).

**Methods**

* `compile()` — Returns the parsed `PoliciesContent` dataclass. Template variable substitution does not apply to structured prompts.
* `variables` — Always returns an empty list.

***

## `PolicyEntry`

Dataclass representing a single policy rule.

| Field             | Type            | Description                                          |
| ----------------- | --------------- | ---------------------------------------------------- |
| `id`              | `str`           | Unique policy identifier.                            |
| `condition`       | `str`           | Condition expression that triggers this policy.      |
| `action`          | `str`           | Action to take when the condition is met.            |
| `criticality`     | `Optional[str]` | Priority level (e.g. `"HIGH"`, `"MEDIUM"`, `"LOW"`). |
| `description`     | `Optional[str]` | Human-readable description of the policy.            |
| `tools`           | `List[str]`     | Tools to use when executing this policy.             |
| `prioritize_over` | `List[str]`     | IDs of other policies this one takes priority over.  |

***

## Content format

Policies can be authored in YAML or JSON. YAML is recommended for readability.

```yaml
policies:
  - id: handoff_policy
    criticality: HIGH
    condition: "The user is abusive or requests a human"
    description: "Detect aggressiveness and hand off."
    action: "Use initiate_human_handoff tool."
    tools:
      - initiate_human_handoff
    prioritize_over:
      - goodbye_policy

  - id: auth_policy
    condition: "Customer provides name and DOB"
    description: "Authenticate the customer."
    action: "Call authenticate_customer with provided details."
    tools:
      - authenticate_customer
```