Variables

Overview

Variables are structured prompts that define persistent variables for agent sessions. Each variable specifies a name, data type, persistence scope, and default value.

Variables 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="variable", so you don't have to.

get_variable (source)

Get a variable prompt by name.

Automatically prefixes the name with variables/ and sets type="variable".

get_variable(
    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,
) -> VariablePromptClient

Parameters

• name — Variable name (without the variables/ 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

VariablePromptClient

---

create_variable (source)

Create a variable prompt.

Automatically prefixes the name with variables/ and sets type="variable".

create_variable(
    *,
    name: str,
    prompt: str,
    labels: List[str] | None = None,
    tags: List[str] | None = None,
    config: Any | None = None,
    commit_message: str | None = None,
) -> VariablePromptClient

Parameters

• name — Variable name (without the variables/ prefix).

• prompt — JSON content string.

• labels — Labels to assign.

• tags — Tags to assign.

• config — Additional config dict.

• commit_message — Optional commit message.

Returns

VariablePromptClient

---

update_variable (source)

Update a variable prompt version.

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

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

Parameters

• name — Variable name (without the variables/ 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_variables (source)

List variable prompts.

list_variables(
    *,
    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_variable (source)

Delete a variable prompt.

Automatically prefixes the name with variables/.

delete_variable(
    name: str,
    *,
    label: str | None = None,
    version: int | None = None,
) -> None

Parameters

• name — Variable name (without the variables/ prefix).

• label — If set, deletes versions carrying this label.

• version — If set, deletes only this specific version.

---

Fetching variables

variables = client.get_variable("session-state")

for v in variables.entries:
    print(v.name, v.type, v.default_value)

---

Creating variables

content = """
{
  "variables": [
    {
      "name": "is_authenticated",
      "type": "boolean",
      "persistence": "customer",
      "default_value": false
    },
    {
      "name": "subscription_plan",
      "type": "string",
      "persistence": "customer",
      "default_value": "guest"
    }
  ]
}
"""

variables = client.create_variable(
    name="session-state",
    prompt=content,
    labels=["production"],
)

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

---

VariablePromptClient

Returned by get_variable() and create_variable().

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[VariableEntry] (property).

Methods

• compile() — Returns the parsed VariablesContent dataclass. Template variable substitution does not apply to structured prompts.

• variables — Always returns an empty list.

---

VariableEntry

Dataclass representing a single variable definition.

Field	Type	Description
name	str	Variable name (e.g. "is_authenticated").
type	str	Data type ("boolean", "string", "number", etc.).
persistence	Optional[str]	Persistence scope ("customer", "session", etc.).
default_value	Any	Default value for the variable.

---

Content format

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

{
  "variables": [
    {
      "name": "is_authenticated",
      "type": "boolean",
      "persistence": "customer",
      "default_value": false
    },
    {
      "name": "language",
      "type": "string",
      "persistence": "session",
      "default_value": "en"
    }
  ]
}