Steps & Workflows

A step is a reusable unit of work. A workflow puts steps in order, with a run policy and a version history. This page covers what goes into each. Workflow Design covers control flow: conditions, loops, parallel branches, waits and sub-workflows.

Steps

A step is defined once and can be used in many workflows.

Field	Purpose
Name & description	What operators see in lists and run views.
Instruction	The model's contract: what to accomplish, what inputs to use, what to return.
Tool allowlist	The ordered tools the step may call. Each tool's resource and scope bound the step's delegated token.
Max rounds	How many model↔tool rounds the step may take (default 10).
Token budget	The step's cumulative token ceiling (default 32,000).
Output schema	Optional JSON Schema. The step's output is validated against it and promoted as structuredOutput_<n>.
Model override	Optional provider and model for this step instead of the agent's own. A workflow step's override takes precedence.

Kinds of step

Kind	What runs
Model	The default: a model conversation over the instruction, calling tools from the allowlist.
Deterministic	No model. The runner selects context entries, shapes them with a JMESPath expression and can apply a tool once per element or chunk. The result is exact, repeatable and costs no tokens. Use it to flatten, filter, de-duplicate or count between model steps.
Sub-workflow	Runs another published workflow as a child run. See Sub-workflows.

Retrieval, skills and clarification apply only to model steps, because the other kinds have no prompt.

Writing good instructions

The instruction is what the model reasons over — treat it like a specification:

• Name the inputs it should read from the run context (e.g. "the candidate FSP number from the run inputs").
• Define the success condition explicitly. If a tool returns a staged/pending outcome that is success (e.g. StagedForReview on a reviewed action), say so: "a StagedForReview result IS the successful outcome — do not retry." Without this, the model may treat it as a failure and retry.
• Say what to return. Later steps see this step's outputs; tell the model what to surface.

Least privilege through the allowlist

A step can call only the tools on its allowlist, and each tool call carries a token scoped to that tool's resource and scope. Keep allowlists short: a narrow allowlist keeps the step's security boundary clear and makes it easier to reuse.

Each tool on the allowlist is either automatic (the default) or requires confirmation. A call to a tool that requires confirmation pauses the run until a person approves it. See Tool calls that need confirmation.

Fetching what a step always needs

Some data a step needs on every run — "the record for this run's subject", say — is known in advance. Instead of hoping the model fetches it, a model step can declare retrieval: tool calls from its allowlist that run before the model starts, with arguments filled in from the run's inputs and earlier steps' results. The results are placed in the model's prompt: small ones in full, large ones as a reference the model reads as much of as it needs. The model saves a round, cannot forget the data, and each retrieval call shows in the run view like any other tool call. A call can reuse an identical earlier call in the same run instead of calling the tool again. See the step retrieval runbook.

Large results

A tool result larger than Execution:MaxInlineToolResultCharacters (4,000 characters by default) is not pasted into the conversation. The model gets a result reference instead (size, a summary and a preview) and uses built-in tools to read what it needs:

Built-in	What it does
read_result	Reads a slice of the result by offset.
search_result	Ranks the result's chunks against a query. With an embedding model configured (Retrieval:EmbeddingProvider and EmbeddingModel), ranking is semantic and the vectors are stored in PostgreSQL (pgvector) for the rest of the run. If embedding fails, the search falls back to literal matching.
summarize_result	Summarizes the result with a cheaper model (Retrieval:SummarizationProvider / SummarizationModel), or the step's own model when none is set. It accepts an optional focus and maxWords.
read_context	Reads a context value too large to show in full in the prompt.

Embedding and summarization calls are billed to the run like any other model call. See the semantic retrieval runbook.

Sharing guidance with skills

Guidance that many steps need, such as a rule table, an output convention or a glossary, belongs in a skill rather than copied into each instruction. A skill is a named, versioned piece of instruction text. Attach it to the model steps that need it on the step's page, and the step places the skills in its prompt in the order you list them. A skill can also be loaded on demand: the model sees only its name and description, and reads the full text when it decides the skill applies. That saves tokens on runs that don't need it.

Each save of a skill creates a new version. A step either follows the latest version, so improving the skill improves every step that uses it, or is pinned to one version that never changes. Before you save, the skill's page shows where it is used and which workflows the edit will affect. A step whose skill is missing, inactive or lacks the pinned version fails rather than running without it. See the skills runbook.

Letting the model ask

A model step can allow clarification. Its model can then pause the run to ask a person a question. See Asking a person for clarification.

Workflows

A workflow is an ordered list of steps. The same step can appear in many workflows, and even twice in one.

• Compose: add steps in execution order, then reorder or remove them at any time. Each workflow step can also carry a condition, a for-each loop, a wait, a parallel group or a model override. See Workflow Design.
• Data flows through context: each step's outputs are promoted into the run's context channel so subsequent steps can reference them. There is no hidden shared state.
• Activate / deactivate: deactivating takes a workflow out of service without losing its history. An inactive workflow is not offered as a workflow tool or over the MCP server.

Draft and published versions

A workflow has one editable draft and an append-only list of published versions (v1, v2, …). Publishing (POST /api/workflows/versions, with optional notes) freezes everything a run executes: the steps, their order and control flow, each step's instruction, limits, schema, model override, tool allowlist, retrieval and skills, and the confirmation tier and default agent. Publishing is refused when nothing changed since the latest version.

• Runs are pinned. A run executes the version it started on for its whole life, including after a wait, a retry or a crash. Publishing v4 does not change a v3 run that is waiting for review.
• Choosing what to run. A launch runs the latest published version by default. Pass workflowVersionNumber to pin an older one, or useDraft: true for a test run of the draft. Schedules, triggers and eval runs can pin a version too.
• Never published workflows run their draft, so existing workflows keep working until someone publishes v1.
• Compare any two versions, or a version and the draft, on the workflow page's Versions card.

Tool names and parameter schemas are not frozen, because they belong to the remote MCP server. See the workflow versions runbook.

Run policy and other workflow settings

Setting	Purpose
Confirmation tier	HumanReview or AutoApply: whether the changes the workflow stages are reviewed before they are applied. External surfaces such as the portal read it. Moving to AutoApply is guarded by the promotion gate.
Default agent	The agent a launch uses when it names none. A launch with neither fails.
Retry policy	Optional maxAttempts (1–10) overriding the platform default. 1 means no automatic retry. See Retries.
Fallback workflow	A workflow started when a run is dead-lettered. See Automation.
Purpose requirement	Every launch must state a purpose input. See Run Inputs.

The promotion gate

Moving a workflow from HumanReview to AutoApply requires evidence. Link an eval suite to the workflow and set a pass score (default 0.98), a number of consecutive passing runs (default 3) and a minimum case count. The promotion is allowed only when the suite is ready for the current published version. Publishing a new version starts a new streak. An administrator with override-workflow-promotion-gate can promote anyway with a written justification, which is recorded in the activity feed. With auto-demote on, a workflow drops back to HumanReview when a later eval run or sampled live verification scores below a floor, or when a new version is published. See the promotion gate runbook.

Moving workflows between environments

A published workflow version can be exported as a workflow package: one JSON file with its steps, run policy, skills and optionally its eval suites, schedules and event triggers. It names the resources, tools, agents and models it needs instead of carrying ids or secrets. Importing it on the Workflow packages page first shows a preview of what is missing and what will be created or updated, then writes everything in one transaction. Importing the same package again updates what it created before rather than making copies, which makes it suitable for promoting a workflow from staging to production and for starting from a template. An import never turns on auto-apply, and it creates schedules and triggers disabled. See the workflow packages runbook.

What depends on what

Observe → Dependencies answers "what breaks if this changes?" Start from a model, resource, tool, agent or skill to see the steps, workflows (draft and published), schedules and triggers that depend on it, with each one's runs, failures and cost over the last 30 days. From a model's graph you can swap it for another across agents and step overrides in one audited operation, optionally after measuring the swap with eval experiments. See the model dependencies runbook.

Execution limits

Runs execute under deterministic guardrails. A run that breaches one fails explicitly, with the limit recorded as the failure reason. It never silently truncates.

Limit	Default	Set by
Model rounds per step	10	The step's max rounds
Tokens per step	32,000	The step's token budget
Tokens per run, including child runs	200,000	Execution:InstanceTokenBudget
Context entries in a step prompt	100	Execution:MaxContextEntries
Context characters in a step prompt	50,000	Execution:MaxContextCharacters
Items in one for-each step	1,000	Execution:MaxIterationItems
Sub-workflow nesting depth	3	Execution:MaxSubWorkflowDepth

Execution:MaxDegreeOfParallelism (default 8) bounds how many branches of one run execute at once. Extra branches wait their turn rather than fail.

Related

• Workflow Design: conditions, loops, parallel branches, waits and sub-workflows.
• Runs: what happens when a workflow executes.
• Run Inputs: parameterizing a run.
• Evaluations: the evidence behind the promotion gate.