Overview

Learn about Step Workflows progressive disclosure pattern for AI agents and when to use it

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

1. Define the workflow as ordered steps (each with a goal, instructions, optional inputs, and transitions)
2. 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
3. Agent collects inputs: The agent follows step instructions and collects any required information
4. Agent submits the step: The agent calls a special dynamic “submit” tool to advance the workflow
5. System validates and transitions: The workflow engine runs on.presubmit, validates inputs, runs on.submit, and either transitions or completes in place
6. 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 has a lifecycle with validation and action execution points:

---

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.

---

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: GPT-4o-mini often sufficient where GPT-4o or GPT-4.1 was previously required
• 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 (Simplified)

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 email format before proceeding
- Always confirm information before moving on
[... 50+ more instructions ...]

Problems:

• Agent sometimes skips validation
• All 50+ instructions visible at once
• Expensive to run (requires GPT-4)
• Hard to maintain

After: Step Workflows

Step 1: GREET
  Goal: Welcome the user
  Instructions: "Greet the user warmly and explain you'll help them with their contact request."

Step 2: COLLECT_NAME
  Goal: Collect user's name
  Inputs: {name: string (required)}

Step 3: COLLECT_EMAIL
  Goal: Collect user's email
  Inputs: {email: string (required)}
  Validation: Must contain @ and .

Step 4: COLLECT_TIME
  Goal: Ask for preferred contact time
  Inputs: {time: enum[morning, afternoon, evening] (required)}

Step 5A: SCHEDULE_PHONE
  (if time is morning/afternoon)

Step 5B: SCHEDULE_EMAIL
  (if time is evening)

Step 6: CONFIRM
  Goal: Confirm all information

Step 7: CLOSE
  Goal: Thank and end
  (terminal step)

Benefits:

• Agent sees only current step
• Validation automatically enforced
• Works with GPT-4o-mini (90% cost reduction compared to GPT-4o)
• Easy to add/remove/modify steps

---

Getting Started

To build your first Step Workflow, see the tutorial section below. You’ll learn:

1. Creating a simple “Hello World” workflow
2. Collecting user inputs with validation
3. Building multi-step workflows with data persistence
4. Adding lifecycle actions for polished experiences
5. Implementing conditional branching logic
6. Handling validation errors and retries
7. Integrating with external tools and systems

Next: Continue to the Tutorial section to start building.

---

Reference

For complete technical reference on step configuration, lifecycle hooks, actions, expressions, and advanced features, see the Reference section below.