Workflows

A workflow guides a conversation through a sequence of steps. Each directory directly inside an assistant's workflows/ directory defines a workflow; each directory inside that workflow defines a step.

Extend the receptionist from Setup with a booking request workflow:

reception/
├── config.yaml
├── base.md
├── default.md
├── functions.yaml
└── workflows/
    └── booking/
        ├── 01-details/
        │   ├── prompt.md
        │   └── functions.yaml
        └── 02-confirm/
            ├── prompt.md
            └── functions.yaml

This example collects and confirms an appointment request. To create an actual booking, add an integration or HTTP function before finishing the workflow.

Start a workflow

Creating the folder makes the workflow part of the configuration. Add a start_workflow function to let the assistant enter it:

- name: start_booking
  description: Start when the caller wants to discuss an appointment request. Do not restart while already collecting that request.
  args: []
  execution:
    type: builtin
    operation: start_workflow
    workflow: booking

workflow is the exact directory name, not a dashboard ID or a display name. It must refer to a workflow with at least one step in this assistant. Starting it selects its first step. No starter function is generated automatically.

Use the function's description to explain when the assistant should call it. You can also add guidance to default.md, such as: “When the caller wants to discuss an appointment request, call start_booking.”

Copy the four files from Steps into the two step directories before syncing this example. Empty directories are not enough.

What changes during a workflow

While a step is active, its prompt.md supplies the current task instructions. The assistant's base.md still applies, and assistant-level functions remain available alongside that step's functions. default.md resumes when the workflow ends.

Steps advance when the assistant calls a transition function. Reaching the end of a prompt does not automatically advance a workflow. Conversation history continues across steps; saved variables can make collected values explicit in later task context.

Only one workflow is active at a time. Calling another start_workflow function switches to that workflow's first step; it does not create a nested workflow to return to later.

Names, references, and limits

A folder named new-appointment is displayed as new appointment, but functions must still reference workflow: new-appointment. Workflows do not need a config.yaml or a workflow-level prompt. Each step owns its prompt and functions.

You can omit workflows/ when the assistant has no workflows. Files such as .github/workflows/ci.yaml are unrelated to assistant workflows and are ignored by the assistant importer.

An assistant supports up to 12 workflows and 24 steps total across those workflows. References cannot cross assistant boundaries. When renaming a workflow folder, update every function that references it in the same commit.