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)

Get a policy prompt by name.

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

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)

Create a policy prompt.

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

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)

Update a policy prompt version.

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

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)

List policy prompts.

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)

Delete a policy prompt.

Automatically prefixes the name with policies/.

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

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

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

---

Creating policies

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.

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