Build a workflow

A workflow runs agents as steps. Use one when a job needs more than one agent, or when the same work should run the same way every time: one agent after another, one agent on every item in a list, or a draft and review that repeat until the review approves.

A single agent is still the simpler choice for a job one agent can do. Build the agents first, test each one on its own, then connect them.

Start from a pattern

Open Workflows and choose New Workflow. Pick the closest starting point; you can change every part of it afterwards:

• Chain — agents run one after another, each receiving the run's input and what the step before returned;
• Draft and review — one agent drafts and another reviews, repeating until the review approves or three passes are done;
• Split and combine — work on every item in a list at the same time, then have one agent combine the results;
• Blank — a single agent step to build from.

Give the workflow a Name and a Description that says when to use it. The description is what people and agents read when they decide whether this is the workflow they want.

Add steps

Steps run in the order they are listed. Add them with Add Agent Step, Add Parallel Step, or Add Workflow Step:

• An agent step runs one agent.
• A parallel step runs an agent on several parts at once. Choose One part per item in a list to give each item of a list its own part, or An agent plans the parts to let a planning agent decide how to divide the work. Set how many parts may run At the same time, the Most parts, and how many Failures allowed before the whole step fails.
• A workflow step runs another workflow as one step and returns its output. Turn on Use the workflow as it's saved now to pin that version, so later changes to the other workflow don't change this one.

Every step has a Key, a short name such as draft or review. Later steps read a step by its key, so the builder updates every reference when you rename one.

Tell each step what to do

A step's Instruction is plain text. It tells the agent what to do and never contains run data, so one agent's output can't rewrite the next agent's instructions. The workflow-wide Task applies to every step without its own instruction.

Data reaches an agent only through the step's input. Pick values from the run's input or from what earlier steps returned. If you don't set an input, the first step receives the run's input and later steps receive the run's input plus the output of the step before. Workflow expressions covers every value you can read and how to reach inside one.

Run a step only when it's needed

Turn on Only run this step when a condition holds and write the condition, for example $steps.review.output.approved == true. When the condition is false the step is skipped, and later steps see it as skipped rather than failed.

Decide what happens when a step fails

Choose If it fails on each step:

• Stop the workflow — the run fails with this step's error. This is the default.
• Continue with the next step — later steps see the failure and can react to it.
• Try again — repeat the step a set number of times. Only failures that are safe to repeat are tried again.
• Hand it to another agent — run a backup agent in its place. Agent steps only.

A workflow step can stop or continue; it isn't tried again, because repeating another whole workflow isn't known to be safe.

Pass files between steps

Under Files, add the files a step needs. Each one comes from the run's input or from an earlier step, and gets the name the step sees it by. Mark it Required if the step can't go on without it; a step that is skipped never needs its files.

Repeat steps until the result is right

Turn on Repeat steps to run part of the workflow again. Repeat from is the first step that repeats; everything from there to the last step runs again until the stop condition holds, such as a review approving the draft. Most passes caps how many times it can go round.

Set the contracts and limits

Under Input and output contracts, describe the input the workflow accepts and the output it returns. The Run page builds its form from the input contract, and a run whose output doesn't match the output contract fails its result check. Output picks what a run returns; by default it's the output of the last step.

Limits cap the time, tokens and tool calls one run may use, across all of its steps. Individual steps can have limits of their own.

Test the workflow

Save, then choose Run and start a run with realistic input. The run page shows each step as it happens: what it received, what it returned, parts of a parallel step, and every pass through a loop. A step that is waiting for a person, to answer a question or approve a tool, shows its controls in place.

If a run fails or is cancelled, open the step where you want to begin again and choose Rerun From Here. Steps before it keep their results; that step and everything after it run again with the workflow as it's saved now.

Share it and run it automatically

A new workflow is private to you. Use Sharing on its page to share it with the workspace. Everyone who can see it can run it, and its steps run with the access of the person or automation that starts it.

A schedule or inbound webhook can start a workflow. Create one from the Triggers section of the workflow's page, or choose the workflow as the target under Schedules or Inbound Webhooks. When a run is still going at the next fire, the trigger skips that fire by default; choose Start another run anyway if overlapping runs are fine.

Nobody is watching a triggered run, so the workflow is checked before a trigger is saved. Running unattended on the workflow's page lists anything that would stop it: a tool that needs approval nobody can give, a model the workspace doesn't allow, or a connection that isn't set up for unattended use. Fix those on the agents it names.

Saving a change can break a trigger, for example by removing an agent the trigger's owner can't run. The save then lists the triggers it would turn off and asks before turning them off.

Environment, budgets and rules

A workflow can have its own environment variables. Open Environment from its page to assign shared workspace variables or add values only this workflow uses. Its steps read them; runs nested deeper use their own settings.

Budgets, model rules and egress rules can apply to a single workflow. They govern every run inside a run of that workflow, including nested workflows' runs. See manage a workspace.

Turn it off or delete it

Turn off Active to stop a workflow from being run; its triggers skip their runs until you turn it back on. A workflow can't be deleted while another workflow runs it as a step, or while a schedule or inbound webhook starts it. Its past runs stay in history after it's deleted.