Execution Model

How workflows execute from trigger to completion

Understanding the execution model helps you design reliable workflows and debug issues effectively.

Build Time vs Run Time

Workflows have two distinct phases:

Build Time

Design your workflow in the editor. Define steps, configure tools, and set up dependencies.

Run Time

The runner interprets and executes the manifest. Steps run in dependency order as data flows through.

Execution Timeline

When a workflow runs, it follows this timeline:

1. Trigger

   Execution begins via API call, schedule, MCP, or manual run

2. Validate

   Input parameters validated, manifest loaded

3. Execute

   Steps run according to dependency graph

4. Handle

   Errors caught, retries attempted if configured

5. Return

   Final result returned to caller

Step Execution Patterns

Sequential

Steps with dependencies run one after another

Parallel

Independent steps run simultaneously

Conditional

Steps run only when when condition is true

Loop

Steps repeat for each item via forEach

Sequential Execution

Steps with needs wait for their dependencies:

steps:
  - id: step_a
    tool: TOOL_A

  - id: step_b
    tool: TOOL_B
    needs: [step_a]  # Waits for step_a

  - id: step_c
    tool: TOOL_C
    needs: [step_b]  # Waits for step_b

Execution order: step_a → step_b → step_c

Parallel Execution

Steps without shared dependencies run in parallel:

steps:
  - id: input
    tool: INPUT_TEXT

  - id: branch_a
    tool: TOOL_A
    needs: [input]

  - id: branch_b
    tool: TOOL_B
    needs: [input]  # Runs parallel with branch_a

  - id: merge
    tool: TOOL_C
    needs: [branch_a, branch_b]  # Waits for both

Execution order: input → (branch_a ∥ branch_b) → merge

Conditional Execution

Use when for conditional logic:

steps:
  - id: classify
    tool: GEMINI_CHAT
    input:
      - name: prompt
        value: "Classify as 'urgent' or 'normal': {{inputs.message}}"

  - id: urgent_handler
    tool: SLACK_POST_MESSAGE
    needs: [classify]
    when: "'{{steps.classify.result.content}}' == 'urgent'"
    input:
      - name: message
        value: "URGENT: {{inputs.message}}"

  - id: normal_handler
    tool: GMAIL_SEND
    needs: [classify]
    when: "'{{steps.classify.result.content}}' == 'normal'"
    input:
      - name: body
        value: "{{inputs.message}}"

Only one handler executes based on the classification result.

Loop Execution (forEach)

Process collections with forEach:

steps:
  - id: get_items
    tool: INPUT_JSON
    input:
      - name: value
        value: '[{"name": "Alice"}, {"name": "Bob"}, {"name": "Carol"}]'

  - id: greet_each
    tool: GEMINI_CHAT
    forEach: "{{steps.get_items.result}}"
    needs: [get_items]
    input:
      - name: prompt
        value: "Write a greeting for {{item.name}}"

The step executes once for each item in the collection.

Failure Modes

Failure Type	Cause	Handling
Validation Error	Invalid input parameters or manifest	Execution stops immediately
Tool Error	External service failure or timeout	Step marked failed
Timeout Error	Step exceeds configured time limit	Step terminated
Dependency Error	Required step failed	Dependent steps skipped
Condition Error	Invalid when expression	Step skipped with warning

Step Status States

Each step transitions through these states:

Status	Description
Pending	Waiting for dependencies to complete
Running	Currently executing
Success	Completed successfully
Failed	Execution failed with error
Skipped	Condition not met or dependency failed

Variable Resolution

Variables are resolved at execution time:

Pattern	Resolved To
{{inputs.name}}	Input parameter value
{{steps.step_id.result}}	Full result of completed step
{{steps.step_id.result.field}}	Specific field from step result
{{secrets.KEY_NAME}}	Credential from workspace secrets
{{item}}	Current item in forEach loop
{{item.field}}	Field from current loop item

Error Handling Best Practices

1. Validate Early: Use INPUT_* tools to validate data at the start
2. Check Outputs: Add validation steps after critical operations
3. Use Conditions: Handle different outcomes with when clauses
4. Design for Failure: Consider what happens when external services fail
5. Review History: Use execution history to analyze failures

Debugging Tips

Issue	Solution
Step not running	Check needs dependencies are satisfied
Wrong data	Verify variable reference syntax
Condition not working	Test when expression with actual values
Loop not iterating	Ensure forEach target is an array
Timeout	Increase step timeout or optimize logic

What’s Next?

Debug Workflows

Learn debugging techniques

YAML Reference

Complete manifest syntax reference