Overview

Step Workflows enable progressive disclosure for AI agents: instead of providing all instructions in a monolithic prompt, you define a multi-step workflow where only the current step’s context is visible to the agent. This reduces cognitive load, improves focus, and makes complex workflows testable and maintainable.

What Are Step Workflows?

Traditional AI agent prompts provide all instructions at once—a “monolithic” approach that can overwhelm the agent with too much information. Step Workflows break complex conversations into discrete stages, revealing instructions progressively as the conversation evolves.

Progressive Disclosure

From Anthropic’s Effective context engineering for AI agents:

Letting agents navigate and retrieve data autonomously also enables progressive disclosure—in other words, allows agents to incrementally discover relevant context through exploration. Each interaction yields context that informs the next decision…

The Step Workflows feature applies this progressive disclosure pattern to agent conversations. Instead of giving the agent all instructions upfront, the agent discovers instructions incrementally for each step by interacting with the workflow tool.

How It Differs from Monolithic Prompts

Aspect	Monolithic Prompt	Step Workflows
Instructions	All visible at once	Revealed step-by-step
Agent Focus	Must filter relevant info	Only sees current step
Compliance	Agent may skip/reorder	Enforced sequence
Maintenance	Change affects everything	Isolated per step
Testing	Full end-to-end only	Step-by-step verification

When to Use Step Workflows

Step Workflows are ideal for:

Complex workflows with multiple stages (verification, data collection, conditional routing)
State-dependent logic where next actions depend on previously collected information
Compliance requirements where specific text must be delivered verbatim (legal disclosures, HIPAA notices)
Testable conversations where you need to verify state transitions and data collection

Not recommended for:

Simple single-turn interactions
Open-ended conversations without clear structure
Workflows with fewer than 3 distinct stages

How It Works

Basic Workflow Lifecycle

Define the workflow as ordered steps (each with a goal, instructions, optional inputs, and transitions)
System primes the workflow: On the first turn, the runtime injects a synthetic tool call/response so the agent learns the current submit-tool pattern and receives the first step’s instructions
Agent collects inputs: The agent follows step instructions and collects any required information
Agent submits the step: The agent calls a special dynamic “submit” tool to advance the workflow
System validates and transitions: The workflow engine runs on.presubmit, validates inputs, runs on.submit, and either transitions or completes in place
Repeat until a terminal step is submitted

Visual: Workflow State Machine

A multi-step workflow progresses through steps as the agent collects inputs and triggers transitions:

Visual: Step Lifecycle

Each step fires a fixed sequence of lifecycle hooks around the agent’s submit call: on.enter fires once per step entry; on.presubmit and on.submit fire on every submission. See the Reference for the full firing-order rules.

Key Concepts

Steps

A step is a single stage in your workflow. Each step has:

ID: Unique identifier (e.g., COLLECT_NAME)
Goal: Brief description of what this step accomplishes
Instructions: Guidance for the agent on what to do
Inputs: Data to collect (optional, defined as JSON Schema)
Actions: Operations to perform at lifecycle points (optional)
Next: Which step(s) to transition to after completion

Submit Tool

The submit tool is a dynamically-generated tool that the agent calls to advance the workflow. Its schema changes based on the current step’s inputs. For example:

Step 1 collects name → submit tool expects {name: string}
Step 2 collects email → submit tool expects {email: string}

Terminal Steps

A terminal step has no next field, indicating it’s the final step. When a terminal step is submitted, the workflow completes. Important: Entering a terminal step does not complete the workflow by itself. The submit tool still has to be called on that terminal step. For no-input terminal steps, your instructions or tools.call: true must still drive that final submission.

State Management

The workflow maintains state across steps:

Current step inputs: Data collected for the active step
Workflow-local state: Persistent local.* values stored for use across multiple steps
Global variables: Saved values available outside the workflow after completion
Completed steps: History of which steps have been submitted

External Tool Calls

Steps workflows can queue external tool calls from on.start, on.enter, or on.submit, but the runtime does not automatically write the resulting tool output back into workflow state. If later branching depends on an external tool result, use one of these patterns:

branch on vars.* only if the endpoint already persists the needed values there, or
have the agent read the tool result and resubmit normalized fields through the submit tool.

Composing Multiple Workflows

A single agent can run more than one workflow in the same conversation — each workflow is an independent state machine with its own submit tool, isolated state, and lifecycle events. Each workflow declares a start mode that controls when it activates:

start: "auto" (default) — the workflow activates at session start. This matches the single-workflow examples in this guide.
start: "manual" — the workflow’s submit tool is visible to the agent from session start, but the workflow stays dormant until something invokes it (typically a call action from another workflow). Useful for sub-routines that should only run on demand — e.g. a “look up patient record” helper called by a triage workflow when it reaches that point.

The headline composition is primary + secondary: an auto-starting primary workflow drives the conversation and uses a call action to activate a manual secondary workflow when needed. Each workflow’s instructions stay focused on its own job, and the secondary’s on.start actions only fire when they’re relevant. See Workflow Configuration in the reference for the full schema and a code example.

Benefits

1. Improved Agent Compliance

By limiting what the agent sees at each stage, Step Workflows dramatically improve adherence to instructions:

Reduced skipping: Agent cannot skip steps (enforced sequence)
Better focus: Agent only considers current step’s requirements
Verbatim text: Actions can deliver exact text without agent paraphrasing

2. Cost Reduction

Progressive disclosure allows using smaller, cheaper AI models:

Smaller context: Each step has minimal instructions (not thousands of characters)
Efficient models: workflows that previously required a frontier model often run reliably on a smaller, cheaper one
Reduced tokens: less redundant information passed to the model

3. Maintainability

Changes to one step don’t affect others:

Isolated changes: Modify step instructions without side effects
Easy reordering: Change workflow sequence without rewriting everything
Clear structure: Self-documenting workflow stages

4. Testability

Individual steps can be tested in isolation:

Step-by-step verification: Confirm each stage works correctly
State inspection: Check data collection at each point
Reproducible scenarios: Easy to recreate specific workflow states

Real-World Example

Before: Monolithic Prompt

You are a contact form agent. Follow these steps:

1. Greet the user warmly
2. Collect their name
3. Collect their email (must contain @ and .)
4. Ask for preferred contact time (morning, afternoon, or evening)
5. If they prefer morning/afternoon, schedule a phone call
6. If they prefer evening, schedule an email follow-up
7. Confirm all information
8. Thank them and end the conversation

Remember to be polite and professional, validate the email format before
proceeding, and always confirm information before moving on. [... more
instructions ...]

The agent sometimes skips validation, sees every instruction on every turn, and is hard to maintain because changing one stage means re-reading the whole prompt.

After: Step Workflow

The same flow expressed as a workflow. Each step’s instructions are revealed only when the agent reaches it:

{
  "steps": [
    {
      "id": "GREET",
      "goal": "Welcome the user",
      "instructions": ["Greet the user warmly and explain you'll help them with their contact request."],
      "next": ["COLLECT_NAME"]
    },
    {
      "id": "COLLECT_NAME",
      "goal": "Collect the user's name",
      "inputs": [{"name": "user_name", "required": true}],
      "on": {"submit": [{"action": "save"}]},
      "next": ["COLLECT_EMAIL"]
    },
    {
      "id": "COLLECT_EMAIL",
      "goal": "Collect the user's email",
      "inputs": [{"name": "user_email", "format": "email", "required": true}],
      "on": {"submit": [{"action": "save"}]},
      "next": ["COLLECT_TIME"]
    },
    {
      "id": "COLLECT_TIME",
      "goal": "Ask for preferred contact time",
      "inputs": [{"name": "contact_time", "enum": ["morning", "afternoon", "evening"], "required": true}],
      "on": {"submit": [{"action": "save"}]},
      "next": [
        {"if": "inputs.contact_time == 'evening'", "id": "SCHEDULE_EMAIL"},
        {"id": "SCHEDULE_PHONE"}
      ]
    }
  ]
}

The agent only ever sees the current step’s instructions and inputs. Conditional branching, validation, and data persistence are handled by the workflow engine instead of the prompt. The full tutorial walks through this example end-to-end.

Next steps

Continue to the Tutorial to build your first workflow, or jump to the Reference for the complete configuration documentation.

Introduction to Syllable

Tutorials

Account

Workspaces

Resources

What Are Step Workflows?

Progressive Disclosure

How It Differs from Monolithic Prompts

When to Use Step Workflows

How It Works

Basic Workflow Lifecycle

Visual: Workflow State Machine

Visual: Step Lifecycle

Key Concepts

Steps

Submit Tool

Terminal Steps

State Management

External Tool Calls

Composing Multiple Workflows

Benefits

1. Improved Agent Compliance

2. Cost Reduction

3. Maintainability

4. Testability

Real-World Example

Before: Monolithic Prompt

After: Step Workflow

Next steps

Introduction to Syllable

Tutorials

Account

Workspaces

Resources

Documentation Index

​What Are Step Workflows?

​Progressive Disclosure

​How It Differs from Monolithic Prompts

​When to Use Step Workflows

​How It Works

​Basic Workflow Lifecycle

​Visual: Workflow State Machine

​Visual: Step Lifecycle

​Key Concepts

​Steps

​Submit Tool

​Terminal Steps

​State Management

​External Tool Calls

​Composing Multiple Workflows

​Benefits

​1. Improved Agent Compliance

​2. Cost Reduction

​3. Maintainability

​4. Testability

​Real-World Example

​Before: Monolithic Prompt

​After: Step Workflow

​Next steps

What Are Step Workflows?

Progressive Disclosure

How It Differs from Monolithic Prompts

When to Use Step Workflows

How It Works

Basic Workflow Lifecycle

Visual: Workflow State Machine

Visual: Step Lifecycle

Key Concepts

Steps

Submit Tool

Terminal Steps

State Management

External Tool Calls

Composing Multiple Workflows

Benefits

1. Improved Agent Compliance

2. Cost Reduction

3. Maintainability

4. Testability

Real-World Example

Before: Monolithic Prompt

After: Step Workflow

Next steps