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.

Every step directory requires a nonempty prompt.md and a functions.yaml containing a YAML array. Use [] if a step has no functions. Put each function in the step where the assistant should be able to call it.

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.

Put lasting instructions in base.md and the current task in prompt.md. See Prompts for how instructions and context are combined.

Build a workflow

Extend the receptionist from Assistants 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.”

Add the following prompts and functions to both step directories before syncing this example. Empty directories are not enough.

Collect the request

Ask for the caller's name and preferred appointment date and time, one question
at a time. Clarify ambiguous dates using the local time in context.
Do not promise availability. Once all details are clear, call proceed.

- name: proceed
  description: Continue once the caller's name and preferred appointment date and time are clear.
  args: []
  execution:
    type: builtin
    operation: transition
    target: finish_step

Confirm the request

Summarize the caller's name and requested date and time, then ask if they are correct.
If details need changing, call change_details.
If the caller confirms, explain that no appointment has been booked by this
example assistant, then call finish_request. Do not claim the request was sent.

- name: change_details
  description: Return to collecting details when the caller wants to correct the request.
  args: []
  execution:
    type: builtin
    operation: transition
    target: regress_workflow
    step: 01-details
- name: finish_request
  description: Finish after the caller confirms the request and understands that no appointment has been booked.
  args: []
  execution:
    type: builtin
    operation: transition
    target: exit_workflow

Add a booking function and update the confirmation prompt when you connect an appointment service. Completing a step does not itself perform an external action.

Step order and names

Step directories sort by name using numeric comparison: 2-details precedes 10-confirm. Alphabetical comparison breaks ties. Numeric prefixes are optional; using 01-, 02-, and so on makes the intended sequence easy to see.

For display, a leading numeric prefix followed by - is removed and hyphens become spaces: 01-collect-details becomes collect details. References always use the full directory name, including the prefix.

When renaming a step directory, update every function that references it in the same commit.

Transition targets

Transitions are allowed only in a step's functions.yaml. Their owning step is inferred from the file location. You do not specify an owner ID. Destinations must exist in the same assistant. For explicit jumps, omit workflow to use the current workflow.

target is always a string: finish_step, exit_workflow, regress_workflow, or a step reference. These three behavior names are reserved. Regression requires a sibling step field; other transitions must omit it. workflow is allowed only for explicit step jumps.

GitHub configuration and the dashboard use the same transition operation. In the dashboard, add a built-in Transition, choose its behavior and destination, and describe when the assistant should call it. Destinations are configured by the author, not passed as model-generated function arguments.

Regression and required follow-up steps

Regression remembers one return step. If D regresses to A and A calls finish_step, the assistant returns to D and clears the return. If A explicitly transitions to B, that cancels the return: B's finish_step advances normally to C.

Use explicit destinations for required follow-up work, such as checking availability after changing an appointment date. Regression supports earlier steps in the current workflow; nested regressions are rejected. Exiting or starting another workflow also clears the pending return.

All transitions preserve saved variables and conversation context. Step prompts remain exactly as authored. A destination step should use saved information and validate any prerequisites that may be missing or outdated. Transitions do not undo completed actions or execute external functions automatically.

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.

A step supports up to 17 functions, including transitions. Function names must be unique within the file and must not collide with assistant-level functions. Different steps can reuse a name such as proceed.