Workflow Node Versioning#

Dify's workflow engine supports multiple backend implementations of the same logical node type, disambiguated by a version string. This allows legacy and new variants to coexist in the registry without renaming the underlying node type enum value.

Backend: Node Registry & Version Resolution#

The registry is a two-level map: NodeType → { version_string → Node class }. It lives in the Node base class (from the graphon library) and is bootstrapped once at startup by register_nodes(), which recursively imports:

• graphon.nodes — built-in node implementations
• core.workflow.nodes — Dify-specific overrides and extensions

Import-time side effects cause each node class to self-register. A node declares its type and version via two class-level attributes:

Both classes share BuiltinNodeTypes.AGENT as node_type — the version string plus an optional discriminator differentiate them.

Version resolution at execution time is handled by resolve_workflow_node_class():

1. Look up the node_type in the registry.
2. For Agent nodes with version="2", check for the presence of agent_node_kind="dify_agent":
   • If present, route to DifyAgentNode
   • If absent, route to the legacy AgentNode implementation (preserving historical v2 tool-parameter semantics)
3. For all other cases, try to find the class registered under node_version.
4. Fall back to the "latest" sentinel if no exact match is found.

This means older saved graphs referencing version "1" continue to execute with AgentNode, historical graphs with version="2" without the discriminator use AgentNode, and new graphs with version="2" and agent_node_kind="dify_agent" use DifyAgentNode.

Node construction is delegated to DifyNodeFactory.create_node(), which reads the type, version, and node_data from the persisted node config, calls _resolve_node_class() (now passing node_data to support discriminator-based routing), then dispatches to a per-type kwargs factory. For BuiltinNodeTypes.AGENT, the factory checks issubclass(node_class, DifyAgentNode) to branch between V1 (plugin-strategy) and V2 (agent-backend microservice) initialization 1.

Discriminator check is implemented by is_dify_agent_node_data(), which inspects the three-part signature (type=agent, version=2, agent_node_kind=dify_agent). The discriminator is used at dispatch time, publish validation, DSL packaging, Composer candidate filtering, and Node Output Inspector routing to ensure only explicit Dify Agent nodes are treated as such.

The mutable view NODE_TYPE_CLASSES_MAPPING wraps the registry as a MutableMapping, enabling test overrides without mutating the global Node class state 2.

Frontend: Feature Flags & Node Palette#

The UI maintains a parallel distinction between the legacy agent block and the V2 block.

BlockEnum defines both as separate entries in web/app/components/workflow/types.ts:

• BlockEnum.Agent = 'agent'
• BlockEnum.AgentV2 = 'agent-v2'

Both are included in WORKFLOW_COMMON_NODES, the master list of blocks available to the workflow engine. The selector palette shows both as separate entries, both titled "Agent".

Conditional exposure is controlled by useAvailableNodesMetaData():

• Reads the NEXT_PUBLIC_ENABLE_AGENT_V2 environment variable via isAgentV2Enabled().
• Detects the workflow mode via useIsChatMode().
• Computes shouldUseAgentV2 = agentV2Enabled && (!isChatMode || isAgentV2InChatflowEnabled()) 3.
• Builds the full metadata list (nodesMetaData) containing both BlockEnum.Agent and BlockEnum.AgentV2.
• Filters the node picker list (availableNodesMetaData): if shouldUseAgentV2, removes BlockEnum.Agent; otherwise removes BlockEnum.AgentV2 4.
• Populates nodesMetaDataMap from the unfiltered list, ensuring both Agent and Agent V2 validators remain accessible 5.

The result: exactly one variant appears in the node picker UI at any time, but both validators are retained in nodesMap. This allows workflows containing legacy Agent nodes to pass validation and publish successfully even after Agent V2 is enabled, while still guiding users toward the newer implementation for new additions.

Chat mode (Chatflow) handling: By default, Agent V2 is restricted to Workflow mode only. The separate NEXT_PUBLIC_ENABLE_AGENT_V2_IN_CHATFLOW flag (defaults to false) allows opt-in enablement of Agent V2 in Chatflow. When this flag is set to true, the isAgentV2InChatflowEnabled() helper returns true, and Agent V2 nodes become available in Chatflow mode.

Wire-type normalization: When a BlockEnum.AgentV2 node is placed, its defaultValue.type is normalized back to BlockEnum.Agent ('agent') before being written to the graph 6. The persisted type field remains 'agent' for both variants; the backend uses version ("1" vs "2") plus the agent_node_kind discriminator to select the correct class at runtime.

Key Source Files#