# 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)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3355)

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`.

```python
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)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3394)

Create a routine prompt.

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

```python
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)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3429)

Update a routine prompt version.

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

```python
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)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3453)

List routine prompts.

```python
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)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3474)

Delete a routine prompt.

Automatically prefixes the name with `routines/`.

```python
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

```python
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

```python
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.

```yaml
- 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
```