dify-workflow-skills

name	dify-workflow-skills
description	Build, edit, and diagnose Dify workflow DSL files. Use when creating workflows, modifying nodes/edges, validating structure, troubleshooting runtime failures (empty URL, invalid variables, branch deadlock, chat_http!=200), and designing robust LLM automation with error handling.

Dify Workflow DSL Builder

Build, edit, and validate Dify workflow DSL (Domain-Specific Language) files for creating AI-powered automation workflows.

This skill is based on the Dify open-source platform's workflow engine, which powers both Workflow apps and Advanced Chat apps with a React Flow-based visual editor.

Architecture Overview

Dify workflows use a queue-based, event-driven architecture with:

Backend (Python - Execution Engine)

• GraphEngine: Central orchestrator managing workflow execution
• WorkerPool: Thread pool for parallel node execution
• VariablePool: Centralized variable management across nodes
• EdgeProcessor: Handles conditional routing and branch selection
• Graph Validator: Ensures workflow integrity before execution

Frontend (React/TypeScript - Visual Editor)

• React Flow: Canvas-based node graph editor
• Zustand Store: State management for nodes, edges, and viewport
• WorkflowContext: Provides workflow state to component tree
• BaseNode: Common wrapper for all node types with handles, headers, and interactions
• Panel System: Dynamic configuration panels for each node type
• Hook Injection Pattern: Decouples UI from execution logic (draft sync, workflow run)

Integration Layer

• workflow: Core canvas engine (generic React Flow implementation)
• workflow-app: Application wrapper (business logic, API integration, lifecycle management)
• Draft Management: Auto-save with debouncing and sendBeacon for safety
  • Uses debounced sync to prevent excessive API calls
  • Cancels pending syncs on unmount to avoid race conditions
  • Tracks loaded state with isWorkflowDataLoaded flag
• Features System: Optional features (file upload, speech-to-text, citations) integrated with workflow
• Trigger Status Management: Separate store for tracking trigger node enable/disable state
  • Trigger nodes can be enabled or disabled independently
  • Status persists across workflow editor sessions
  • Used for webhook, schedule, and plugin triggers

Core Capabilities

1. Create new workflows - Generate complete workflow YAML files from descriptions
2. Edit existing workflows - Add, modify, or remove nodes and connections
3. Validate workflows - Check DSL syntax and structure
4. Design complex flows - Build workflows with LLM nodes, code execution, branching, loops, and error handling
5. Error handling strategies - Implement fail-branch, retry, or default-value error handling
6. Diagnose workflow failures - Root-cause empty outputs, invalid variables, API failures, and branch blocking

Diagnostic Mode (新增)

When user asks: 排查, 诊断, 为什么没有URL, chat_http 400, 无效变量, 卡住, 分支不执行, Dify 工作流异常.

Diagnostic Principles

1. Evidence first: collect result CSV, raw JSON, and event traces before proposing fixes.
2. Classify failure type: transport/API vs graph logic vs variable binding vs parser mismatch.
3. Smallest safe fix: change only the minimal nodes/edges required.
4. Never directly edit escaped data.code in YAML text: always use Python patch script (yaml.safe_load -> modify -> yaml.safe_dump).
5. Preserve baseline: avoid editing baseline directories and keep hotfix outputs as new files when possible.

Failure Taxonomy (优先级顺序)

1. Transport/API failures

• Signals: upload_http != 201, chat_http != 200, timeout, save API 400.
• Typical cause: transient API failure, invalid key/user, upstream service instability.

2. Graph execution deadlock

• Signals: chat succeeds but no downstream output (output_file_url empty), specific node never appears in events.
• Typical cause: code node waits on inputs from non-executed branch.

3. Variable contract failures

• Signals: Dify invalid variable warning, red exclamation, runtime unresolved value.
• Typical cause: {{#conversation.xxx#}} referenced but missing in conversation_variables.

4. Extraction/semantic mismatch

• Signals: mostly WARN, module differences, low hit rate but HTTP success.
• Typical cause: parser normalization mismatch, naming drift, prompt schema mismatch.

Standard Diagnostic Workflow (8 Steps)

1. Lock scope: subject/workflow file/sample IDs/time window.
2. Collect evidence:

• detail csv (real_*_detail_*.csv)
• raw payload (*_raw_*/**/*.json)
• run logs (*_bg_*.log)

3. Compute failure profile:

• status distribution (PASS/WARN/FAIL)
• top reasons
• empty URL ratio

4. Trace output chain backward:

• from output node (<file-url> or result node) to save node to merge node to branch condition.

5. Check branch exclusivity and dependency completeness:

• if node input references a node that does not run in this branch, treat as blocking risk.

6. Propose fix pattern:

• duplicate downstream chain for branch-specific path, or
• split merge node, or
• add guard/default path.

7. Apply via patch script:

• clone nodes/edges with new IDs and update selectors.

8. Verify by re-test:

• same samples, compare URL fill rate and FAIL rate.

High-Value Fix Patterns

Pattern A: Empty URL due to branch-shared merge node

• Symptom: one branch outputs URL, another branch always empty.
• Root cause: merge/save nodes shared by two branches; one branch lacks some merge inputs, causing wait.
• Fix:
  1. duplicate merge -> save -> answer tail for missing branch;
  2. bind inputs only from nodes guaranteed to execute in that branch;
  3. update answer variable selectors to new save node.

Pattern B: Intermittent FAIL from chat_http=400

• Symptom: occasional FAIL with same sample; rerun often succeeds.
• Fix:
  1. test runner adds one retry for non-zero return;
  2. keep per-attempt logs;
  3. separate transient from deterministic failures in report.

Pattern C: Invalid conversation variable

• Symptom: Dify marks variable invalid in prompt.
• Fix:
  1. extract Referenced(conversation.*);
  2. diff with Declared(conversation_variables.name);
  3. append missing declarations with matching name/selector.

Diagnostic Output Contract (每次诊断必须给出)

1. Findings (ordered by severity)

• file + node IDs + proof line/log.

2. Root cause

• concise causal chain.

3. Minimal fix

• exact nodes/edges/variables to modify.

4. Verification result

• before/after PASS-WARN-FAIL, URL fill ratio.

5. Residual risk

• what remains and why.

Guardrails for This Skill

1. Do not bulk-reformat YAML or reorder unrelated sections.
2. Do not change baseline directories unless explicitly requested.
3. Prefer generated hotfix files and keep backup snapshots before structural edits.
4. If root cause is uncertain, stop after evidence report and ask for one focused re-test.

Quick Reference

Node Types: See references/node_types.md for complete list including:

• Core Flow: start, end, answer
• LLM & AI: llm, agent, parameter-extractor
• Logic & Control: if-else, question-classifier, loop, iteration
• Data Processing: code, template-transform, variable-aggregator, assigner, list-operator, document-extractor
• External Integration: http-request, tool, knowledge-retrieval, knowledge-index, datasource
• Advanced: trigger-webhook, trigger-schedule, trigger-plugin, human-input

Edge Types and Connections: See references/edge_types.md for:

• Source handle types (source, true/false, success-branch/fail-branch, loop)
• Edge data properties and validation rules
• Common connection patterns

Node Positioning: See references/node_positioning.md for:

• Canvas coordinate system and spacing guidelines
• Layout patterns (linear, branching, error handling, iteration)
• Position calculation formulas

Common Node Properties: All nodes support these internal properties (prefixed with _):

• _runningStatus: Current execution status (running, succeeded, failed)
• _connectedSourceHandleIds/_connectedTargetHandleIds: Connection tracking
• _isSingleRun: Single execution mode for debugging
• _isCandidate: Phantom node during connection drag
• _children: Child nodes for container types (iteration, loop)
• _iterationLength/_iterationIndex: Iteration state tracking
• _loopLength/_loopIndex: Loop state tracking
• _retryIndex: Current retry attempt
• _waitingRun: Queued for execution, human-input

Workflow Structure: See references/workflow_structure.md for complete DSL format

Edge Types: See references/edge_types.md for connection patterns and handle types

Node Positioning: See references/node_positioning.md for layout guidelines

Templates: Check assets/ for example workflows

Creating a New Workflow

Step 1: Understand Requirements

Ask the user:

• What should the workflow do?
• What are the inputs and outputs?
• What processing steps are needed?
• Any conditional logic or error handling?

Step 2: Design Node Flow

Plan the workflow structure:

1. Start node - Define input variables
2. Processing nodes - LLM, code, tools, etc.
3. Control flow - if-else for branching, loop for iteration
4. Error handling - Use fail-branch on code nodes
5. Output aggregation - variable-aggregator to merge branches
6. End node - Define outputs

Step 3: Generate Node IDs

Use scripts/generate_id.py to create unique node IDs:

python3 scripts/generate_id.py 5  # Generate 5 unique IDs

Or generate in Python/JavaScript:

# Python
import time
node_id = str(int(time.time() * 1000))

// JavaScript (used in Dify frontend)
const nodeId = `${Date.now()}`

Special ID patterns for container nodes:

• Iteration/Loop start nodes: ${parentNodeId}start
• Example: If iteration node ID is 1736668800000, its start node ID is 1736668800000start

Step 4: Build the Workflow

Create the complete YAML structure with:

• Top-level metadata (kind, version, app)
• App section (name, description, icon)
• Workflow section with features and graph
• Nodes array with positions
• Edges array connecting nodes

Template to use: Start from assets/simple_llm_workflow.yml for basic flows

Step 5: Validate

Check the workflow structure for common issues:

• All nodes have unique IDs
• All edges reference existing node IDs
• Start and end nodes exist
• Required fields are present
• Variable references use correct syntax: {{#node_id.field#}}

Common Workflow Patterns

Pattern 1: Simple LLM Flow

Start → LLM → End

Use case: Basic question answering, text generation

Template: assets/simple_llm_workflow.yml

Pattern 2: Error Handling Flow

Start → Code (with fail-branch) → [Success → Aggregator] / [Fail → LLM Recovery → Retry → Aggregator] → End

Use case: Robust data processing with error recovery

Template: assets/error_handling_workflow.yml

Key points:

• Set error_strategy: fail-branch on code node
• Fail branch provides error_message and error_type variables
• Use variable-aggregator to merge success/fail branches
• Reference aggregator output in end node

Pattern 3: Conditional Routing

Start → If-Else → [True → Handler A] / [False → Handler B] → Aggregator → End

Use case: Route requests based on content/type

Template: assets/conditional_workflow.yml

Key points:

• If-else has true and false sourceHandles
• Use comparison operators: contains, starts_with, is_empty, etc.
• Combine conditions with logical_operator: "and" or "or"

Pattern 4: Loop Processing

Start → Loop → [Process Items] → Loop End → End

Use case: Iterative processing with break conditions

Key points:

• Set loop_count for maximum iterations
• Define break_conditions to exit early
• Loop maintains state across iterations

Editing Existing Workflows

Adding a Node

1. Read the existing workflow file
2. Generate a new unique node ID
3. Add node to workflow.graph.nodes array with:
   • Unique ID and position
   • Node type and configuration
   • Proper sourcePosition/targetPosition
4. Add edge(s) to workflow.graph.edges connecting the new node
5. Update any dependent nodes (e.g., end node outputs)

Removing a Node

1. Identify the node ID to remove
2. Remove node from workflow.graph.nodes
3. Remove all edges referencing that node ID (as source or target)
4. Update downstream nodes that referenced the removed node's outputs

Modifying Connections

1. Find edge by source and target node IDs
2. Update edge source, target, sourceHandle, or targetHandle
3. Update edge data.sourceType and data.targetType to match actual node types
4. Update edge id to follow naming convention: {source_id}-{handle}-{target_id}-target

Variable Reference Syntax

Variables are managed in a centralized VariablePool and use the format: {{#node_id.field_name#}}

Variable Types (VarType)

Dify supports these variable types for type-safe data flow:

Primitive Types:

• string: Text data
• number: Floating-point numbers
• integer: Whole numbers
• boolean: true/false values
• secret: Encrypted sensitive data (API keys, passwords)

Complex Types:

• object: JSON objects
• file: Single file reference
• array: Generic array
• array[string]: Array of strings
• array[number]: Array of numbers
• array[object]: Array of objects
• array[boolean]: Array of booleans
• array[file]: Array of files
• array[any]: Array of mixed types
• any: Any type (use sparingly)

Special Types:

• contexts: Knowledge retrieval results
• iterator: Iteration input variable
• loop: Loop input variable

File Upload Configuration

When using file input types (file, files, file-list), you can configure upload settings:

Default File Upload Settings:

allowed_file_upload_methods: ['local_file', 'remote_url']
max_length: 5  # Maximum number of files
allowed_file_types: ['image']  # Options: image, document, audio, video, custom
allowed_file_extensions: []  # e.g., ['.pdf', '.docx']

Upload Methods:

• local_file: Direct file upload from local system
• remote_url: Upload file from URL

File Type Categories:

• image: Image files (JPG, PNG, GIF, etc.)
• document: Document files (PDF, DOCX, TXT, etc.)
• audio: Audio files (MP3, WAV, etc.)
• video: Video files (MP4, AVI, etc.)
• custom: Custom file types (specify extensions)

Input Variable Types (InputVarType)

Start nodes use these input types for user-facing variables:

• text-input: Single-line text input
• paragraph: Multi-line text input
• select: Dropdown selection
• number: Numeric input
• checkbox: Boolean checkbox
• url: URL input with validation
• files: Multiple file upload
• file: Single file upload
• file-list: Multiple file list
• json: JSON input (object or array)
• json_object: JSON object with schema validation
• contexts: Knowledge retrieval context
• iterator: Iteration variable
• loop: Loop variable

Variable Selector Pattern

The variable pattern regex: {{#[a-zA-Z0-9_]{1,50}(?:\.[a-zA-Z_][a-zA-Z0-9_]{0,29}){1,10}#}}

Selector structure: [node_id, variable_name, ...optional_nested_keys]

• First element: node ID that produced the variable
• Second element: variable name or output field
• Additional elements: nested object keys or array indices (for FileSegment/ObjectSegment)

ValueSelector: Array format used in DSL (e.g., ['1732007415808', 'text'])

• Represented as arrays in YAML: value_selector: ['node_id', 'field_name']
• Converted to template syntax in prompts: {{#node_id.field_name#}}

System Variables

Available via sys node ID:

• {{#sys.query#}} - User query/input
• {{#sys.files#}} - Uploaded files
• {{#sys.conversation_id#}} - Current conversation ID
• {{#sys.user_id#}} - User identifier
• {{#sys.dialogue_count#}} - Number of dialogue turns
• {{#sys.app_id#}} - Application ID
• {{#sys.workflow_id#}} - Workflow ID
• {{#sys.workflow_run_id#}} - Current execution ID
• {{#sys.timestamp#}} - Current timestamp

Common Output Fields by Node Type

LLM Node:

• {{#node_id.text#}} - Generated text response (type: string)
• {{#node_id.usage#}} - Token usage information (type: object)
• {{#node_id.reasoning_content#}} - Model reasoning (if enabled) (type: string)

Agent Node:

• {{#node_id.usage#}} - Token usage information (type: object)

Code Node:

• {{#node_id.output_name#}} - Named outputs defined in node config
• {{#node_id.error_message#}} - Error message (fail-branch only) (type: string)
• {{#node_id.error_type#}} - Error type (fail-branch only) (type: string)

Start Node:

• {{#node_id.variable_name#}} - Input variables defined in start node

If-Else Node:

• {{#node_id.condition_result#}} - Boolean condition result

Loop Node:

• {{#node_id.output#}} - Loop output array
• {{#node_id.iteration#}} - Current iteration number

HTTP Request Node:

• {{#node_id.body#}} - Response body (type: string)
• {{#node_id.status_code#}} - HTTP status code (type: number)
• {{#node_id.headers#}} - Response headers (type: object)
• {{#node_id.files#}} - Downloaded files if response is file (type: array[file])

Tool Node:

• {{#node_id.text#}} - Tool output text (type: string)
• {{#node_id.files#}} - Tool output files (type: array[file])
• {{#node_id.json#}} - Tool output JSON (type: array[object])

Knowledge Retrieval Node:

• {{#node_id.result#}} - Retrieved knowledge segments (type: array[object])

Template Transform Node:

• {{#node_id.output#}} - Transformed output (type: string)

Question Classifier Node:

• {{#node_id.class_name#}} - Classification result (type: string)
• {{#node_id.usage#}} - Token usage information (type: object)

Parameter Extractor Node:

• {{#node_id.__is_success#}} - Extraction success indicator (type: number)
• {{#node_id.__reason#}} - Extraction failure reason (type: string)
• {{#node_id.__usage#}} - Token usage information (type: object)
• Plus custom extracted parameters defined in node config

Variable Aggregator:

• {{#node_id.output#}} - Aggregated output from merged branches

File Object Structure (when file type is used):

• name - File name (type: string)
• size - File size in bytes (type: number)
• type - File type category (type: string)
• extension - File extension (type: string)
• mime_type - MIME type (type: string)
• transfer_method - Transfer method used (type: string)
• url - File URL (type: string)
• related_id - Related resource ID (type: string)

Knowledge Retrieval Result Structure:

{
  "content": "",
  "title": "",
  "url": "",
  "icon": "",
  "metadata": {
    "dataset_id": "",
    "dataset_name": "",
    "document_id": [],
    "document_name": "",
    "document_data_source_type": "",
    "segment_id": "",
    "segment_position": "",
    "segment_word_count": "",
    "segment_hit_count": "",
    "segment_index_node_hash": "",
    "score": ""
  }
}

Environment and Conversation Variables

Environment variables (defined at app level):

• Access via special node ID: env
• Example: {{#env.API_KEY#}}

Conversation variables (session state):

• Access via special node ID: conversation
• Example: {{#conversation.user_context#}}

Example Variable Usage

# In LLM prompt template
prompt_template:
  - role: system
    text: "You are a helpful assistant."
  - role: user
    text: "Process this input: {{#1732007415808.user_input#}}"

# In code node
variables:
  - ["1732007415808", "user_input"]
  - ["1732007420123", "processed_data"]

# Accessing nested object fields
text: "File name: {{#upload_node.files.name#}}"
text: "API response status: {{#http_node.status_code#}}"

Node Positioning

Position nodes on the canvas for visual clarity:

Layout Constants (from Dify frontend):

• NODE_WIDTH: 240 pixels
• X_OFFSET: 60 pixels (horizontal spacing)
• NODE_WIDTH_X_OFFSET: 300 pixels (node width + spacing)
• Y_OFFSET: 39 pixels
• START_INITIAL_POSITION: { x: 80, y: 282 }
• NODE_LAYOUT_HORIZONTAL_PADDING: 60 pixels
• NODE_LAYOUT_VERTICAL_PADDING: 60 pixels
• NODE_LAYOUT_MIN_DISTANCE: 100 pixels

Container Node Padding:

• Iteration/Loop containers:
  • top: 65, right: 16, bottom: 20, left: 16
• Z-index for iteration/loop: 1 (container), 1002 (children)

Horizontal spacing: 300-400 pixels between connected nodes Vertical spacing:

• Same level: same y-coordinate
• Branches: offset by 150-200 pixels

Example positions:

Start: x=80, y=282 # Initial position
LLM: x=380, y=282  # Start + NODE_WIDTH_X_OFFSET
Code: x=680, y=282
End: x=980, y=282

For branching:

If-else: x=380, y=300
True branch: x=680, y=200
False branch: x=680, y=450
Aggregator: x=980, y=300

Container nodes (Iteration/Loop):

• Start node inside container: { x: 24, y: 68 } (relative to container)
• Children nodes have parentId set to container ID
• Children have higher z-index (1002) than container (1)

See references/node_positioning.md for detailed layout patterns and formulas.

Visual Editor Integration

The DSL you create is rendered in the Dify visual workflow editor built with React Flow.

How DSL Maps to UI

Nodes → Visual blocks on canvas with:

• Icon and title (from type and title fields)
• Connection handles (based on node type and error_strategy)
• Configuration panel (node-specific form in right sidebar)
• Status indicators (running, succeeded, failed)

Edges → Bezier curves connecting nodes with:

• Visual styling based on state (hovering, selected, running)
• Labels for branching paths (true/false, classification labels)
• Color coding for success/fail branches

Viewport → Canvas view settings:

viewport:
  x: 0      # Pan offset X
  y: 0      # Pan offset Y
  zoom: 1.0 # Zoom level (0.1 to 2.0)

Frontend Component Architecture

When your DSL is loaded into the editor:

1. WorkflowContextProvider initializes Zustand store with nodes/edges
2. ReactFlow renders the canvas with custom node components
3. BaseNode wraps each node with common UI (handles, headers)
4. Panel System shows configuration forms when node is selected
5. Hook System manages draft auto-save and execution

UI Features Not in DSL

These UI-only properties are managed by the frontend (don't include in DSL):

• _hovering, _connectedNodeIsHovering: Mouse interaction state
• _connectedSourceHandleIds, _connectedTargetHandleIds: Computed from edges
• _runningStatus, _singleRunningStatus: Runtime execution state
• _isCandidate: Temporary phantom node during connection drag
• selected: Node selection state

Important: Only include persistent properties in your DSL (id, type, title, position, configuration). Runtime UI state is computed by the editor.

Error Handling Strategy

Error Strategies

Dify supports multiple error handling strategies defined in the node configuration:

1. fail-branch (recommended for code/http nodes):

• Creates alternative execution path on error
• Provides error_message and error_type variables
• Uses sourceHandle: "fail-branch" in edge configuration
• Success path uses sourceHandle: "success-branch"
• Requires variable-aggregator to merge with success path before continuing to end node
• Allows graceful error recovery and custom error handling logic

2. default-value:

• Returns a predefined default value on error
• Continues main execution path without branching
• Simpler but less robust than fail-branch
• Good for non-critical operations where fallback values are acceptable

3. abort (default):

• Stops the entire workflow execution on failure
• No additional configuration needed
• Used when errors are unrecoverable

4. retry:

• Configurable retry logic with max retries and intervals
• Defined in node's retry_config section
• Useful for transient failures (network issues, rate limits)
• Supported on: LLM, Tool, HTTP Request, Code nodes only

Retry Configuration Structure:

retry_config:
  max_retries: 3        # Maximum retry attempts (default: 3)
  retry_interval: 100   # Interval between retries in ms (default: 100)

Implementing Fail-Branch Error Handling

In node configuration:

error_strategy: fail-branch

In edges array:

# Success path
- id: code_node-success-branch-next_node-target
  source: code_node_id
  target: aggregator_id
  sourceHandle: success-branch
  targetHandle: target

# Failure path
- id: code_node-fail-branch-error_handler-target
  source: code_node_id
  target: error_handler_id
  sourceHandle: fail-branch
  targetHandle: target

Available error variables in fail-branch:

• {{#node_id.error_message#}} - Human-readable error description
• {{#node_id.error_type#}} - Error type classification

Validation Checklist

Before finalizing a workflow, verify:

Structural Validation

• All node IDs are unique and properly formatted (numeric strings or valid identifiers)
• Workflow has exactly one root node (start, datasource, or trigger node)
• Workflow has at least one end node
• All edges reference valid source and target node IDs that exist in the nodes array
• No circular dependencies that would create infinite loops (except intentional loop nodes)
• Root node is correctly identified and accessible

Edge and Connection Validation

• All edge IDs are unique
• Edge sourceHandle values match node types:
  • Standard nodes: "source" (default)
  • If-else/Question-classifier: "true", "false", or classification label
  • Code/HTTP with error handling: "success-branch" or "fail-branch"
  • Loop nodes: "loop" for continuation
• Edge targetHandle is typically "target" for most nodes
• Edge data.sourceType matches the actual source node type
• Edge data.targetType matches the actual target node type
• Branching paths (from if-else, question-classifier) have edges for all possible outcomes
• Fail-branch edges exist when error_strategy: fail-branch is used

Variable and Data Flow Validation

• Variable references use correct syntax: {{#node_id.field#}}
• All referenced variables exist in upstream nodes (nodes that execute before current node)
• Variable selectors match actual output fields of referenced nodes
• System variables use correct sys prefix: {{#sys.query#}}
• Environment variables use env prefix if needed
• No undefined variable references that would cause runtime errors

Error Handling Validation

• Nodes with error_strategy: fail-branch have both success and fail edges
• Branching paths merge at variable-aggregator before reaching end node
• Variable aggregator receives inputs from all branch paths
• Default values are provided when using error_strategy: default-value
• Retry configurations are valid (max retries, intervals) if using retry strategy

Node Configuration Validation

• Required fields are present for each node type (see node_types.md)
• Node positions are set for visual layout (x, y coordinates)
• LLM nodes have valid model configurations (provider, name, mode)
• Code nodes specify valid language (python3 or javascript)
• HTTP request nodes have valid URLs and methods
• Loop nodes have valid loop_count and break conditions
• If-else nodes have properly structured conditions with valid operators

Workflow Execution Validation

• No nodes are unreachable (all nodes can be reached from root node)
• All execution paths eventually lead to an end node or answer node
• Container nodes (iteration, loop) have proper start/end node pairs
• Human-input nodes are used appropriately (workflow will pause for input)
• Trigger nodes (webhook, schedule) are not mixed with standard start nodes

Node Execution Types

Dify categorizes nodes by their execution behavior. Understanding these types helps design correct workflows:

EXECUTABLE (Standard Logic Nodes)

Execute logic and produce outputs. Most common node type.

• Examples: llm, code, http-request, knowledge-retrieval, template-transform
• Behavior: Execute when all input dependencies are satisfied
• Source Handle: "source" (or "success-branch"/"fail-branch" with error handling)
• Outputs: Defined by node type (see Variable Reference section)

BRANCH (Conditional Routing Nodes)

Control flow by choosing between multiple paths based on conditions.

• Examples: if-else, question-classifier
• Behavior: Evaluate conditions and activate one or more output edges
• Source Handles:
  • If-else: "true", "false"
  • Question-classifier: classification labels (custom)
• Important: Unselected paths are marked as "skipped" and don't execute downstream

CONTAINER (Sub-graph Management)

Manage nested execution contexts with iterations or loops.

• Examples: iteration, loop
• Behavior: Execute internal sub-graph multiple times
• Components:
  • Parent container node
  • Internal start node (iteration-start, loop-start)
  • Internal end node (iteration-end, loop-end)
• Source Handle: "loop" for iteration/loop continuation
• State Management: Maintain loop variables and iteration counts

RESPONSE (Output Streaming)

Stream outputs to users in real-time.

• Examples: answer, end
• Behavior: Output results and potentially complete workflow
• Usage: Answer nodes can appear mid-workflow; End nodes terminate execution

ROOT (Entry Points)

Serve as workflow entry points.

• Examples: start, datasource, trigger-webhook, trigger-schedule, trigger-plugin
• Behavior: First node to execute; no incoming edges
• Important: Only ONE root node per workflow
• Constraint: Standard start nodes and trigger nodes cannot coexist

Nodes That Support Output Variables

The following node types can produce output variables that other nodes can reference:

• Start, TriggerWebhook, TriggerPlugin
• LLM, Agent
• KnowledgeRetrieval
• Code
• TemplateTransform
• HttpRequest
• Tool
• VariableAssigner, VariableAggregator
• QuestionClassifier
• ParameterExtractor
• Iteration, Loop
• DocumentExtractor (DocExtractor)
• ListFilter (list-operator)
• DataSource

Note: Nodes not in this list (like if-else, end, answer) typically don't produce reusable output variables, though some may have limited internal state.

Workflow Execution Model

Execution Flow

1. Initialization: GraphEngine enqueues root node into ReadyQueue
2. Worker Execution: Worker threads pull nodes from ReadyQueue and execute them
3. Event Emission: Workers push events (started, succeeded, failed) to event_queue
4. Edge Processing: Dispatcher processes events and identifies downstream nodes
5. Dependency Resolution: Downstream nodes added to ReadyQueue when dependencies satisfied
6. Parallel Execution: Multiple workers execute independent nodes concurrently
7. Completion: Workflow ends when End node executes or execution fails

Edge States

Edges can be in three states during execution:

• UNKNOWN: Initial state, not yet evaluated
• TAKEN: Edge is traversed (condition met or path selected)
• SKIPPED: Edge is not traversed (condition failed or alternative path chosen)

Workflow Execution Status

Workflows progress through these states:

• SCHEDULED: Queued but not yet started
• RUNNING: Currently executing
• SUCCEEDED: Completed without errors
• FAILED: Terminated due to unhandled error
• PARTIAL_SUCCEEDED: Completed with handled errors (via fail-branch or default-value)
• STOPPED: Manually stopped or aborted
• PAUSED: Waiting for human input (human-input node)

Node Running Status

Individual nodes track their execution state with these statuses:

• NOT_START: Node hasn't started execution yet
• WAITING: Node is queued and waiting to execute
• LISTENING: Node is listening for events (trigger nodes)
• RUNNING: Node is currently executing
• SUCCEEDED: Node completed successfully
• FAILED: Node failed with unhandled error
• EXCEPTION: Node failed but error was handled
• RETRY: Node is retrying after failure
• STOPPED: Node execution was stopped

Important UI State Properties (runtime only, not in DSL):

• _runningStatus: Current execution status
• _singleRunningStatus: Status when running single node
• _waitingRun: Node is queued for execution
• _retryIndex: Current retry attempt number
• _isSingleRun: Node is in single-run debug mode

Best Practices for Execution

1. Parallel vs Sequential: Independent nodes execute in parallel automatically. Use edges to enforce sequence when needed.
2. Error Boundaries: Use fail-branch on critical nodes to prevent workflow abortion
3. Merge Points: Always use variable-aggregator to merge branches before convergence
4. Loop Safety: Set reasonable loop_count limits and clear break conditions
5. Human Input: Plan for paused state when using human-input nodes

Resources

scripts/

• generate_id.py - Generate unique node IDs for workflows
• validate_workflow.py - Validate workflow DSL syntax (requires PyYAML)

references/

• node_types.md - Complete reference of all Dify node types with examples
• workflow_structure.md - Detailed DSL structure and format specification

assets/

• simple_llm_workflow.yml - Basic start→LLM→end template
• error_handling_workflow.yml - Template with fail-branch error handling
• conditional_workflow.yml - Template with if-else branching

Tips for Success

1. Start simple: Begin with basic flows, add complexity incrementally
2. Use templates: Adapt existing templates rather than starting from scratch
3. Validate early: Check structure before adding many nodes
4. Plan error handling: Consider what can fail and how to handle it
5. Name clearly: Use descriptive node titles for maintainability
6. Reference docs: Consult node_types.md for field requirements
7. Test incrementally: Build and test workflows step by step