> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syllable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://www.anthropic.com/engineering/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:

```mermaid theme={null}
stateDiagram-v2
    direction LR
    [*] --> Step1: Start
    Step1 --> Step1: retry (validation fails)
    Step1 --> Step2: submit succeeds
    Step2 --> Step2: retry
    Step2 --> Step3A: conditional route A
    Step2 --> Step3B: conditional route B
    Step3A --> [*]: terminal step
    Step3B --> [*]: terminal step

    note right of Step1
        Each step: collect inputs → validate → transition
    end note
```

### Visual: Step Lifecycle

Each step fires a fixed sequence of lifecycle hooks around the agent's submit call:

```mermaid theme={null}
flowchart LR
    subgraph "Step Lifecycle"
        A[Enter step<br/>on.enter] --> B[Agent collects inputs]
        B --> C[Submit<br/>on.presubmit]
        C --> D{Validate}
        D -->|fail| B
        D -->|pass| E[on.submit]
        E --> F{Next step?}
        F -->|same step| B
        F -->|different step| A
        F -->|none| H[Workflow complete]
    end

    style A fill:#e1f5fe
    style C fill:#fff3e0
    style E fill:#e8f5e9
```

`on.enter` fires once per step entry; `on.presubmit` and `on.submit` fire on every submission. See the [Reference](./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](./reference#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:

```json theme={null}
{
  "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](./tutorial-overview) to build your first workflow, or jump to the [Reference](./reference) for the complete configuration documentation.