Routines

Overview

Routines are structured prompts that define step-by-step agent workflows. Each routine contains an ordered list of steps that form a directed graph.

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

get_routine (source)

Get a routine prompt by name.

Automatically prefixes the name with routines/ and sets type="routine". Accepts the same caching and retry options as get_prompt.

get_routine(
    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,
) -> RoutinePromptClient

Parameters

• name — Routine name (without the routines/ 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

RoutinePromptClient

---

create_routine (source)

Create a routine prompt.

Automatically prefixes the name with routines/ and sets type="routine".

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

Parameters

• name — Routine name (without the routines/ 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

RoutinePromptClient

---

update_routine (source)

Update a routine prompt version.

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

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

Parameters

• name — Routine name (without the routines/ 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_routines (source)

List routine prompts.

list_routines(
    *,
    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_routine (source)

Delete a routine prompt.

Automatically prefixes the name with routines/.

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

Parameters

• name — Routine name (without the routines/ prefix).

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

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

---

Fetching routines

routine = client.get_routine("deposits")

print(len(routine.steps))  # number of steps

for step in routine.steps:
    print(step.step, step.name, step.type)

---

Creating routines

content = """
- step: "1"
  name: "Check Input"
  type: node
  condition: "some_var is True"
  tool: my_tool
- step: "2"
  name: "Reply"
  type: finish
  description: "Reply to the user with the result."
"""

routine = client.create_routine(
    name="my-routine",
    prompt=content,
    labels=["production"],
)

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

---

RoutinePromptClient

Returned by get_routine() and create_routine().

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.

• steps — List[RoutineStep] (property).

Methods

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

• variables — Always returns an empty list.

---

RoutineStep

Dataclass representing a single step in a routine workflow. Fields mirror the backend schema. Required: step.

Field	Type	Description
step	str	Unique step ID (e.g. '1', '2-1_1').
name	str	Human-readable label.
type	str	Step type: node, branch, finish, branchnode.
description	Optional[str]	What this step does.
tool	Optional[str]	Tool to invoke at this step.
condition	Optional[str]	Branching logic (for branch type).
input	Optional[str]	Input specification.
output	Optional[str]	Output specification.

---

Content format

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

- step: "1"
  name: "Start"
  type: node
  description: "Begin the process."
  tool: my_tool
  condition: "is_authenticated is True"

- step: "2"
  name: "Decision Point"
  type: branch
  condition: "If X → step 3, else → step 2-1_1"

- step: "2-1_1"
  name: "Branch Child"
  type: branchnode
  description: "Handles the alternative path."

- step: "3"
  name: "End"
  type: finish