Agent Node Data Models#

Dify's workflow engine has two versions of the Agent node, both sharing BuiltinNodeTypes.AGENT as their node_type but distinguished by a version string. Their Pydantic node-data models live in separate modules:

Both inherit from graphon.entities.base_node_data.BaseNodeData (external graphon==0.6.0 package), which supplies the common type and version fields.

V1: AgentNodeData#

AgentNodeData is the model for legacy plugin-strategy–based agent nodes.

Optional fields (with defaults)#

Nested: AgentInput#

Each value in agent_parameters is an AgentInput:

Supporting enums#

• ParamsAutoGenerated (IntEnum) — CLOSE=0, OPEN=1 1: signals whether agent parameters were auto-generated.
• AgentOldVersionModelFeatures (StrEnum) 2: LLM capability flags used when resolving model compatibility for older SDK versions — TOOL_CALL, MULTI_TOOL_CALL, AGENT_THOUGHT, VISION, STREAM_TOOL_CALL, DOCUMENT, VIDEO, AUDIO.

Referenced types#

• MemoryConfig (from graphon) — window: WindowConfig (enabled: bool, size: int | None) and optional role_prefix: RolePrefix (user: str, assistant: str).
• ToolSelector (from api/core/tools/entities/tool_entities.py) — holds provider_id, tool_name, tool_description, tool_configuration, tool_parameters, and optional credential_id.

V2: DifyAgentNodeData#

DifyAgentNodeData is intentionally minimal — it represents the node slot only; all agent configuration is stored externally.

Fields#

Validation#

A @model_validator(mode="after") enforces version == "2" 3. Deserializing a node with a different version raises a ValueError immediately.

The required agent_node_kind field allows historical type=agent, version=2 nodes (which used a V2 tool-parameter format but preceded the Dify Agent feature) to be distinguished from new Dify Agent nodes. Historical nodes lacking this field are routed to the legacy Agent V1 implementation at dispatch and validation 4 5.

V2 carries no agent configuration directly. The actual agent identity and settings are stored in a separate Agent Soul (AgentSoulConfig) JSON snapshot in AgentConfigSnapshot.config_snapshot, linked via a WorkflowAgentNodeBinding row. The bound agent and its configuration are resolved separately at validation and runtime 6.

Validation Behavior for Unconfigured Nodes#

Because DifyAgentNodeData has no binding fields, an unbound V2 node is schema-valid at the Pydantic level. Binding enforcement is layered on top by WorkflowAgentNodeValidator:

• Draft validation (validate_draft_workflow) — validates the node schema via DifyAgentNodeData.model_validate but silently skips a missing binding. An unconfigured node is not an error in a draft. 6
• Publish validation (validate_published_workflow) — a missing binding is a hard error; the workflow cannot be published with an unbound V2 agent node. 6

Key Source Files#