SystemTce/dify-skills

Dify Workflow Design SKILL

Master the core knowledge and best practices for Dify workflow design

Quick Navigation

• Workflow Overview
• Core Node Types
• Design Patterns
• Workflow Templates
• Variable System
• Best Practices

---

Workflow Overview

Dify Workflow is a visual AI application orchestration system that implements complex business logic through a combination of nodes and edges.

Core Concepts

• Node: The basic execution unit of a workflow; each node performs a specific function
• Edge: Connects nodes, defining data flow and execution order
• Variable: Passes data between nodes
• DSL (Domain Specific Language): YAML-formatted workflow definition language

Workflow Types

1. Workflow: Standard workflow, suitable for complex multi-step processing
2. Advanced Chat: Advanced conversational application supporting workflow orchestration
3. Agent: Intelligent agent for autonomous decision-making and tool invocation

Execution Model

• Queue-Driven: Node scheduling based on Ready Queue
• Event-Driven: Node execution generates event streams
• Parallel Execution: Supports 2-8 worker threads for parallel processing
• Streaming Response: Supports real-time streaming output

---

Core Node Types

1. Start Node

Function: Entry point of the workflow, defines input variables

Configuration Example:

- data:
    desc: ''
    selected: false
    title: Start
    type: start
    variables:
    - label: User Input
      max_length: 1000
      required: true
      type: text-input
      variable: user_input
  id: start
  type: custom

Detailed Documentation: nodes/start.md

---

2. LLM Node

Function: Invokes large language models for reasoning and generation

Configuration Example:

- data:
    type: llm
    model:
      provider: openai
      name: gpt-4
      completion_params:
        temperature: 0.7
        max_tokens: 2000
    prompt_template:
    - id: system
      role: system
      text: "You are a professional assistant"
    - id: user
      role: user
      text: "{{#sys.query#}}"
    context:
      enabled: true
      variable_selector: ["knowledge", "result"]
  id: llm

Key Parameters:

• model: Model configuration (provider, name, parameters)
• prompt_template: Prompt template (supports system and user messages)
• context: Context configuration (enables knowledge base retrieval results)
• memory: Conversation memory configuration
• vision: Vision capabilities configuration (supports image input)

Detailed Documentation: nodes/llm.md

---

3. Agent Node

Function: Intelligent agent that autonomously invokes tools based on user needs

Configuration Example:

- data:
    type: agent
    agent_parameters:
      instruction:
        type: constant
        value: "Based on user needs, call the appropriate tools to complete the task"
      model:
        type: constant
        value:
          provider: openai
          model: gpt-4
          completion_params:
            temperature: 0.7
      query:
        type: constant
        value: "{{#sys.query#}}"
      tools:
        type: constant
        value:
        - enabled: true
          provider_name: time
          tool_name: current_time
          type: builtin
        - enabled: true
          provider_name: duckduckgo
          tool_name: ddgo_search
          type: builtin
    agent_strategy_name: function_calling
  id: agent

Supported Strategies:

• function_calling: Function calling (recommended)
• react: ReAct reasoning mode

Detailed Documentation: nodes/agent.md

---

4. Knowledge Retrieval Node

Function: Retrieves relevant information from the knowledge base (RAG)

Configuration Example:

- data:
    type: knowledge-retrieval
    dataset_ids:
    - "dataset-uuid-1"
    - "dataset-uuid-2"
    query_variable_selector: ["start", "sys.query"]
    retrieval_mode: single
    single_retrieval_config:
      model:
        provider: openai
        name: text-embedding-3-small
      top_k: 3
      score_threshold: 0.7
      reranking_model:
        provider: cohere
        model: rerank-english-v2.0
  id: knowledge

Retrieval Modes:

• single: Single retrieval
• multiple: Multiple retrievals

Detailed Documentation: nodes/knowledge-retrieval.md

---

5. Code Node

Function: Executes Python or JavaScript code

Configuration Example:

- data:
    type: code
    code_language: python3
    code: |
      def main(input_text: str) -> dict:
          # Processing logic
          result = input_text.upper()
          return {
              "output": result,
              "length": len(result)
          }
    variables:
    - variable: input_text
      value_selector: ["start", "user_input"]
    outputs:
      output:
        type: string
      length:
        type: number
  id: code

Supported Languages:

• Python 3
• JavaScript (Node.js)

Detailed Documentation: nodes/code.md

---

6. HTTP Request Node

Function: Invokes external HTTP APIs

Configuration Example:

- data:
    type: http-request
    method: POST
    url: "https://api.example.com/endpoint"
    headers:
      Content-Type: application/json
      Authorization: "Bearer {{#env.API_KEY#}}"
    body:
      type: json
      data:
        query: "{{#sys.query#}}"
        options:
          temperature: 0.7
    timeout: 30
  id: http

Supported Methods:

• GET, POST, PUT, DELETE, PATCH

Detailed Documentation: nodes/http-request.md

---

7. Tool Node

Function: Invokes built-in or custom tools

Configuration Example:

- data:
    type: tool
    provider_id: google_translate
    provider_type: builtin
    provider_name: google_translate
    tool_name: translate
    tool_parameters:
      content:
        type: mixed
        value: "{{#sys.query#}}"
      dest:
        type: mixed
        value: "zh-CN"
  id: tool

Tool Types:

• builtin: Built-in tools
• api: API tools
• workflow: Workflow tools

Detailed Documentation: nodes/tool.md

---

8. If-Else Node

Function: Conditional branching control

Configuration Example:

- data:
    type: if-else
    conditions:
    - variable_selector: ["llm", "text"]
      comparison_operator: contains
      value: "keyword"
    logical_operator: and
  id: condition

Supported Operators:

• contains, not contains
• is, is not
• empty, not empty
• >, <, >=, <=, =, !=

Detailed Documentation: nodes/if-else.md

---

9. Iteration Node

Function: Iteratively processes array data

Configuration Example:

- data:
    type: iteration
    iterator_selector: ["start", "items"]
    output_selector: ["iteration_inner", "output"]
    parallel_nums: 3
    error_handle_mode: continue
  id: iteration

Error Handling Modes:

• continue: Continue execution
• stop: Stop iteration

Detailed Documentation: nodes/iteration.md

---

10. Answer Node

Function: Outputs workflow results

Configuration Example:

- data:
    type: answer
    answer: "{{#llm.text#}}"
  id: answer

Detailed Documentation: nodes/answer.md

---

Design Patterns

1. Sequential Pipeline Pattern

Use Case: Simple linear processing flow

Structure:

Start → LLM → Answer

Example: patterns/sequential.md

---

2. Conditional Branching Pattern

Use Case: Execute different processing logic based on conditions

Structure:

Start → LLM → If-Else → [Branch A / Branch B] → Answer

Example: patterns/conditional.md

---

3. Iterative Processing Pattern

Use Case: Batch processing of array data

Structure:

Start → Code → Iteration → LLM → Answer

Example: patterns/iterative.md

---

4. Knowledge Retrieval Pattern (RAG)

Use Case: Knowledge base-based Q&A

Structure:

Start → Knowledge Retrieval → LLM (with context) → Answer

Example: patterns/rag.md

---

5. Multi-Source Aggregation Pattern

Use Case: Integrate information from multiple data sources

Structure:

Start → [Tool1, Tool2, HTTP] → Variable Aggregator → LLM → Answer

Example: patterns/aggregation.md

---

Workflow Templates

Simple Q&A

File: templates/simple-qa.yml

Description: The most basic Q&A workflow

Nodes: Start → LLM → Answer

---

RAG Assistant

File: templates/rag-assistant.yml

Description: Knowledge base-powered intelligent assistant

Nodes: Start → Knowledge Retrieval → LLM → Answer

---

Agent Tool Invocation

File: templates/agent-tools.yml

Description: Intelligent agent autonomously invoking tools

Nodes: Start → Agent → Answer

---

Multi-Step Processing

File: templates/multi-step.yml

Description: Complex multi-step processing flow

Nodes: Start → Code → HTTP → LLM → If-Else → Answer

---

Variable System

System Variables

{{#sys.query#}}              # User query
{{#sys.files#}}              # Uploaded files
{{#sys.conversation_id#}}    # Conversation ID
{{#sys.user_id#}}            # User ID

Node Variables

{{#nodeID.outputField#}}     # Reference node output
{{#llm.text#}}               # LLM text output
{{#knowledge.result#}}       # Knowledge retrieval result
{{#code.output#}}            # Code node output

Conversation Variables

{{#conversation.variableName#}}     # Conversation-level variable

Environment Variables

{{#env.API_KEY#}}            # Environment variable
{{#env.DATABASE_URL#}}       # Database connection

Iteration Variables

{{#item#}}                   # Current iteration item
{{#index#}}                  # Current index

---

Best Practices

1. Modular Design

• Break complex flows into multiple independent nodes
• Use variables to pass data, avoid hardcoding
• Use conditional branches and iteration nodes appropriately

2. Variable Naming Conventions

• Use meaningful variable names
• Follow a consistent naming convention
• Add necessary description information

3. Error Handling

• Add error handling logic to critical nodes
• Use conditional branches to handle exceptions
• Provide friendly error messages

4. Performance Optimization

• Avoid unnecessary node invocations
• Use caching mechanisms appropriately
• Control loop iteration counts
• Use parallel branches to improve performance

5. Maintainability

• Add node descriptions and comments
• Use clear node naming
• Keep workflow structure simple
• Regularly review and optimize

Detailed Content: best-practices.md

---

Next Steps

• Deep dive into Node Type Details
• Explore Design Patterns
• Get started quickly with Workflow Templates
• Read Best Practices to improve your skills

---

Related SKILLs

• 02-plugin SKILL - Develop custom tools and plugins
• 03-performance SKILL - Optimize workflow performance
• 06-reference SKILL - DSL syntax reference

---

Version: v1.0.0 Last Updated: 2026-03-04 Back: Main SKILL