> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/sdk/routines.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.interactive.ai/sdk/routines.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.