Principle:Langgenius Dify Workflow Variable Management
| Knowledge Sources | |
|---|---|
| Domains | Workflow Variables State Management |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Workflow variable management is the typed variable system that governs how environment secrets, per-session conversation state, system-provided context, and node-level inspection data flow through workflow execution and debugging.
Description
Dify workflows operate with three distinct categories of variables, each serving a different scope and lifecycle:
Environment Variables: These are workflow-scoped key-value pairs that persist across all executions. They are configured at design time and typically hold API keys, service URLs, or other configuration secrets. Variables with a value_type of secret are masked in the UI and API responses (displayed as [__HIDDEN__]) to prevent accidental exposure. Environment variables are included in the workflow draft and transmitted during save operations.
Conversation Variables: These variables maintain state across turns within a single conversation session. They are particularly important for chatflow-type workflows where the workflow may be invoked multiple times within a user session. Conversation variables allow workflows to accumulate context, track user preferences, or maintain counters across multiple interactions. They can be inspected and reset during debugging.
System Variables: These are built-in, read-only variables provided by the Dify runtime. They include contextual information such as the current user ID, conversation ID, application ID, and other execution metadata. System variables are available to all nodes within the workflow and provide a standard way to access runtime context without manual configuration.
Variable Inspection: During workflow development and debugging, developers need visibility into variable values at each node. The inspection system provides paginated access to all variables across the entire workflow or scoped to a specific node. This enables developers to trace data flow, verify transformations, and diagnose issues without running the full workflow.
Usage
Variable management is used throughout the workflow lifecycle:
- Design time: Configuring environment variables and defining conversation variable schemas
- Debug time: Inspecting variable values at specific nodes, resetting conversation variables to default or last-run values
- Runtime: The execution engine reads environment and system variables to provide context to nodes; conversation variables are read and written during chatflow turns
- Administration: Managing secret rotation by updating environment variable values
Theoretical Basis
Variable Scoping Model
The variable system follows a hierarchical scoping model where each scope has distinct visibility and mutability rules:
+--------------------------------------------------+
| WORKFLOW SCOPE (Environment Variables) |
| - Configured at design time |
| - Immutable during execution |
| - Secrets masked in API responses |
| |
| +--------------------------------------------+ |
| | SESSION SCOPE (Conversation Variables) | |
| | - Initialized per conversation | |
| | - Mutable during execution | |
| | - Persisted across turns | |
| | | |
| | +--------------------------------------+ | |
| | | EXECUTION SCOPE (System Variables) | | |
| | | - Provided by runtime | | |
| | | - Read-only | | |
| | | - Unique per execution | | |
| | +--------------------------------------+ | |
| +--------------------------------------------+ |
+--------------------------------------------------+
Pagination Strategy for Variable Inspection
The variable inspection system uses a pagination strategy to handle workflows with large numbers of variables. The client requests pages of 100 variables at a time. If the total count exceeds 100, subsequent pages are fetched in parallel and merged:
fetchAllInspectVars(flowType, flowId):
page1 = fetchPage(1)
if page1.total <= 100:
return page1.items
pageCount = ceil(page1.total / 100)
remainingPages = fetchAllInParallel(page 2 .. pageCount)
return page1.items + flatten(remainingPages)
This ensures efficient retrieval even for complex workflows with hundreds of variables while minimizing the number of sequential network requests.
Variable Lifecycle State Machine
Conversation variables follow a lifecycle through inspection and debugging:
[Default Value] --workflow run--> [Current Value]
^ |
| v
[Reset to Default] [Inspect / View]
^ |
| v
[Reset to Last Run] <-------- [Last Run Value]
Developers can reset a conversation variable either to its original default value or to the value it held at the end of the last workflow execution, enabling flexible debugging workflows.