| description | A workflow puts a playbook's functions to work in steps. How steps, versions, triggers and waiting work, and how to inspect a run afterwards. |
|---|
A workflow puts a playbook's functions to work in steps. A workflow can:
- call functions in order, and choose a path from their results;
- repeat a step for each item in a list, or run branches side by side;
- wait for a person, an event or a set time;
- try a failed step again, and give up after a time limit.
Each time a workflow is carried out, that is a run. A run keeps its place when Auto restarts, and goes on from where it was.
A step is one place where a workflow uses a function. The step refers to the function rather than copying it. So "Review campaign brief" can be a step in several workflows and still be called directly by your agent. Other steps decide what happens next, wait, repeat work or handle errors without calling a function.
A workflow can call any function in its own playbook. It can also call another workflow, which is then a subworkflow. The workflow itself reaches nothing outside the playbook: it does that only through its functions.
For example, Build your first workflow builds a workflow with two steps. It reviews a campaign brief with one reasoning function, then passes that review to a second function that drafts feedback. The run keeps both answers.
Saving a workflow creates version 1, and each change saves a new version. A run uses the version that was the latest when it started, and keeps it to the end. So changing a workflow never changes a run that is already under way, and no one can start a run on an older version. A step that calls a function uses that function's latest version at the moment of the call.
Each function a step calls has a run of its own, with its own id, so you can inspect it separately. That run names the workflow run and the step that started it. A step that is tried again starts a fresh run of the function. A restart of Auto does not repeat a function run that already finished.
Terminology defines definition, version, run, step run and attempt.
Your agent puts each job you want done again and again into a workflow of its own, one that owns the job from what starts it to the result you recognize as done, even if it needs only one step. Its steps use the playbook's functions. The agent runs the workflow and shows you the result; later requests can change that workflow.
Other work stays out of the list of workflows, so that list stays the list of jobs you want done. To see what a function answers, or to test it, the agent runs the function on its own. To ask a person, it writes an interaction function, which the workflow that needs the answer calls as a step. To check a service and its setup, it uses its own tools.
The agent supplies the workflow's input when it starts a run. The run then continues on its own, and the agent can check on it later. Every step acts for whoever started the run, with the permissions they had when it started.
Starting and cancelling a run gives the details, including how to repeat a start safely and how to cancel a run.
A trigger starts a run without anyone asking for it. A workflow can have two kinds:
- An event trigger starts a run for each matching event in the playbook. The event can come from another system or another workflow. It can also be one of the playbook's own records, such as a review that succeeded.
- A schedule trigger starts a run at set times, such as 09:00 UTC on working days, or once every fifteen minutes.
A run that a trigger starts acts as the playbook, with permission to read and write that playbook. The run also records the person it works on behalf of: whoever saved or restored the workflow version, provided that person still belongs to the organization. This adds no permissions. When a trigger applies gives the identity rules.
A trigger applies from the moment it is saved; it never reacts to what the playbook recorded before. Limits stop triggers from starting runs without end. A workflow can also record an event of its own. Another workflow's trigger can react to it, and so can a run that waits for that event.
Pausing a workflow stops its triggers until someone resumes it. While it is paused, the times its schedule names and the events its trigger matches start nothing, and it cannot be run by hand or from another workflow. Runs already under way finish. Resuming it makes up nothing it missed: its next run is at the first scheduled time or matching event after the resume. Pausing changes no version, and a version saved while it is paused stays paused. Every function pauses and resumes the same way, and the definition shows who paused it, when and why.
Run a workflow on a schedule or event shows how to add a trigger, and Triggers gives the rules and limits.
Each function a workflow calls has a run of its own, and every run counts toward usage. If the runtime refuses a triggered run because it has reached a usage limit, that run does not start and is not retried. The playbook records a reaction_refused event. The trigger reference explains refusals; the limits of a self-hosted runtime are in the licensing reference.
A run can wait for a function that takes time, for a timer or for an event. It can wait for days without tying up Auto, and a restart does not lose its place.
Two kinds of input reach a run that is already waiting, and neither starts a new run:
- an answer to a request that one of its steps made;
- an event, for input that is not an answer, such as a revised brief: one sent to the run, or one the playbook records while the run listens for its type.
To include a person's decision in a workflow, use an interaction function. For example, it can ask a campaign owner to approve a brief through a chat message, or hold the request for an agent they answer through. The workflow waits, and the person's answer becomes the result of that step. If nobody answers before the request expires, the workflow can catch that and take another path.
Waiting for events gives the rules for events.
A run ends when its last step completes, or earlier if an error stops it, someone cancels it or it runs too long. How a run ends gives each status and its reasons.
Each run has a record of where it stands. It shows the workflow version, who started the run and, once it ends, its result or why it did not succeed. Where the workflow has a page, the run also shows the headline that page gives it. Its history shows what happened, oldest first: each input the run took and the steps that input moved. Each event names the one that led to it, so the history shows the run's branches, retries and waits. The latest event shows what the run is waiting for. The history shows how the run moved, not the data it holds.
Each function a step called has its own run and history. The playbook's events show the workflow run together with every run it started. History and events explains what a playbook records, and Run history and playbook events lists the reads and their fields.
The workflow format describes the workflow document itself.