Execution Model

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:

Trigger

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

Validate

Input parameters validated, manifest loaded

Execute

Steps run according to dependency graph

Handle

Errors caught, retries attempted if configured

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

Validate Early: Use INPUT_* tools to validate data at the start
Check Outputs: Add validation steps after critical operations
Use Conditions: Handle different outcomes with when clauses
Design for Failure: Consider what happens when external services fail
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

Docs

Execution Model

Build Time vs Run Time

Build Time

Run Time

Execution Timeline

Step Execution Patterns

Sequential

Parallel

Conditional

Loop

Sequential Execution

Parallel Execution

Conditional Execution

Loop Execution (forEach)

Failure Modes

Step Status States

Variable Resolution

Error Handling Best Practices

Debugging Tips

What’s Next?

Debug Workflows

YAML Reference

​Build Time vs Run Time

Build Time

Run Time

​Execution Timeline

​Step Execution Patterns

Sequential

Parallel

Conditional

Loop

​Sequential Execution

​Parallel Execution

​Conditional Execution

​Loop Execution (forEach)

​Failure Modes

​Step Status States

​Variable Resolution

​Error Handling Best Practices

​Debugging Tips

​What’s Next?

Debug Workflows

YAML Reference

Build Time vs Run Time

Execution Timeline

Step Execution Patterns

Sequential Execution

Parallel Execution

Conditional Execution

Loop Execution (forEach)

Failure Modes

Step Status States

Variable Resolution

Error Handling Best Practices

Debugging Tips

What’s Next?