Dosu LogoDosu Logo
Ask
Join our Discord
Organization avatar
difyPublic
Dify
Documentsdify
Agent Node Data Models
Agent Node Data Models
Type
Topic
Status
Published
Created
Jul 29, 2026
Updated
Aug 17, 2026
Created by
Dosu Bot
Updated by
Dosu Bot

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:

VersionClassModule
V1 (legacy)AgentNodeDataapi/core/workflow/nodes/agent/entities.py
V2DifyAgentNodeDataapi/core/workflow/nodes/agent_v2/entities.py

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)#

FieldTypeDefaultNotes
agent_strategy_provider_namestr""Provider owning the strategy (e.g. plugin name)
agent_strategy_namestr""Strategy identifier
agent_strategy_labelstr""Human-readable label
agent_parametersdict[str, AgentInput]{}Per-parameter inputs keyed by parameter name
memoryMemoryConfig | NoneNoneConversation window + role-prefix config
tool_node_versionstr | NoneNoneNone → legacy parameter-parsing rules apply

Nested: AgentInput#

Each value in agent_parameters is an AgentInput:

FieldType
valuelist[str] | list[ToolSelector] | Any
typeLiteral["mixed", "variable", "constant"]

Supporting enums#

  • ParamsAutoGenerated (IntEnum) — CLOSE=0, OPEN=1 : signals whether agent parameters were auto-generated.
  • AgentOldVersionModelFeatures (StrEnum) : 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#

FieldTypeDefaultNotes
typeNodeTypeBuiltinNodeTypes.AGENTInherited override
agent_node_kindLiteral["dify_agent"]REQUIREDDiscriminator tag; must be explicitly set to "dify_agent"

Validation#

A @model_validator(mode="after") enforces version == "2" . 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 .

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 .


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.
  • Publish validation (validate_published_workflow) — a missing binding is a hard error; the workflow cannot be published with an unbound V2 agent node.

Key Source Files#

FileRole
api/core/workflow/nodes/agent/entities.pyV1: AgentNodeData, AgentInput, ParamsAutoGenerated, AgentOldVersionModelFeatures
api/core/workflow/nodes/agent_v2/entities.pyV2: DifyAgentNodeData
api/core/tools/entities/tool_entities.pyToolSelector used in V1 AgentInput.value
api/models/agent_config_entities.pyAgentSoulConfig — full agent config snapshot linked from V2 nodes
api/core/workflow/nodes/agent_v2/validators.pyV2 draft/publish binding validation
Documents
Account Activity Tracking
Agent API Routes
Agent App Architecture
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent App Event Architecture
Agent App Input Variables
Agent Cost and Usage Tracking
Agent File Handling
Agent File Upload Configuration
Agent Icon Data Model
Agent Log Event Pipeline
Agent Message History
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Model Settings
Agent Node Data Models
Agent Response Schema
Agent Runtime
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Runtime Backend Initialization
Agent Runtime Layer Provider Registration
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Sandbox SSRF Allowlisting
Agent Shell Layer
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Strategy Plugin Architecture
Agent V2 Architecture
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent V2 Configure Interface
Agent V2 Feature Flags
Agent V2 File and Vision Handling
Agent V2 Variable System
Agent Workflow Node Variable References
API Documentation Pipeline
App Mode Configuration
App Publishing and Embedding
Audio to Text API
Auth Route Architecture
Automatic Rule Generation
Avatar Management
Branding Customization
Browser Tab and State Management
Builtin Tool Provider Credentials
Celery Task Resilience
Chat Action Bar Mobile Visibility
Chat Avatar Rendering
Chatbot Conversation State Recovery
Chatbot Widget Embedding
Collaborative Workflow Editing
Console API DELETE Request Handling
Console Authentication
Conversation Deep-Linking
Credential Encryption and Secret Management
CSV Data Ingestion
Custom Tool Authentication
Custom Tool HTTP Timeout Configuration
Custom Tool OpenAPI Integration
Data Export
Database Migration System
Database Session Management
Database Transaction Isolation
Dataset Batch Import
Dataset Deletion
Dataset Permission Model
Dataset Segmentation Configuration
Dependency Injection and Testability
Dify Agent Server 模块分析 (Commit 55f95dbc)
Dify Agent Monorepo Structure
Dify Agent Server 模块分析 (Commit 55f95dbc)
Dify Cloud Billing
Dify OpenAPI
difyctl CLI
Docker Container Security
Docker Deployment and Upgrades
Docker Frontend Configuration
Docker Image Publishing
Docker Networking
Docker Storage and Permissions
Document Indexing Operations
DocumentSegment Position Assignment
Draft Variable Storage Cleanup
Edition-Based Feature Gating
Elasticsearch Integration
Embedding Cache Integrity
Excel Extractor
External Knowledge Integration
Extractor Encoding Fallback
File Access Control
File Array Handling
File Download Architecture
File Download Security
File Storage Synchronization
File Upload and Download Integrity
File Upload Configuration
File Upload Processing
File URL Resolution
Flask Application Architecture
Flask Blueprint and Route Registration
Graph Streaming Infrastructure
Home Directory Management
HTTP Request Node
HTTP Request Node Key-Value Editor
HTTP Request Node Size Constraints
httpx and Gevent Compatibility
Human Input Node
Hybrid Search
Icon URL Resolution
Iframe Embedding Security
Internationalization and Locale Management
Jina Reranker Integration
JSON-in-Markdown Parsing
JWT Authentication
Keyboard Shortcut Management
Keyword Moderation
Knowledge Base API
Knowledge Base Document Processing
Knowledge Base Metadata Filtering
Knowledge Base Summarization Pipeline
Langfuse Integration
Lexical Editor Integration
LLM Provider Message Validation
LLM Structured Output
Local Development Configuration
Local Embedding Model Deployment
Log Filtering
Markdown Extractor Heading Parsing
Markdown Rendering
Marketplace Plugin Filtering
MCP Client Transport and Connectivity
MCP Protocol Integration for Dify Workflows
MCP OAuth Integration
MCP Protocol Integration
MCP Protocol Integration for Dify Workflows
MCP Provider Architecture
MCP Tool Content Processing
MCP Tool Integration
MCP Protocol Integration for Dify Workflows
MCP Tool Parameter Binding
MCP Tool Provider Management
Messaging Platform Integration
Milvus Integration
Model Provider Error Handling
Monaco Editor Integration
Multi-Tenant Context Propagation
Multimodal Knowledge Base Support
Multimodal Prompt Delivery
N+1 Query Optimization
Next.js Routing and Redirects
Next.js SSR Authentication
Nginx Reverse Proxy Configuration
Notion Extractor Table Parsing
NumPy CPU Compatibility
OAuth Login Flow
Observability and Tracing
OpenAI-Compatible Server Integration
OpenAPI Spec Accuracy
OpenDAL Storage Backend
Ops Trace Data Models
Oracle Database Connectivity
Parallel Workflow Execution
Parent-Child Retrieval Architecture
Plugin API Key Configuration
Plugin Architecture
Plugin Credential Management
Plugin Daemon Architecture
Plugin Daemon Communication
Plugin Daemon Model Parameter Handling
Plugin Database Integrity
Plugin Error Handling
Plugin File Handling
Plugin Lifecycle Management
Plugin Marketplace Connectivity
Plugin Model Caching
Plugin Permissions
Plugin Storage Configuration
Plugin System Timeouts
Plugin Taxonomy and Validation
Plugin Trigger OAuth Refresh
Private Address Detection
Provider Model & Credential Management
Pyrefly Type Checker
RAG Web Crawling Providers
Rate Limiting and Concurrency Control
RBAC Initialization
RBAC Permission Key Lookup
Reasoning Model Integration
Reasoning Tag Filtering
Redis Connection Management
Redis Streaming Resilience
Release Breaking Changes
Remote File Fetching
Remote File Handling and Validation
Retrieval Filtering and Scoring
RTL Locale Support
Sandbox Code Execution
Sandbox Network Isolation
Segment Update and Attachment Lifecycle
Server Deployment Configuration
Service API Error Handling
Service API Pagination
Shell Provider Lifecycle
Snippet Variable Handling
SQLite Test Infrastructure
SSE Stream Lifecycle
SSE Stream Terminal Event Delivery
SSR Data Fetching
SSRF Proxy
Suggested Questions After Answer
Summary Index
Tenant-Isolated Document Indexing Queue
Test Doubles and In-Memory Repositories
TiDB Vector Full-Text Search
Time Tools
Timestamp Management
Tool File URL Signing
Tool Node Input Validation
Tool Provider Authorization
Trace Task Pipeline
User and Tenant Context Propagation
Dify Agent Server 模块分析 (Commit 55f95dbc)
User Roles and Permissions
Variable Pool Falsy Value Handling
Variable Resolution and Template Substitution
Vector Database Plugin Architecture
Vector Store Integration
Weaviate Vector Store
Web Container Docker Configuration
Webhook Trigger System
WebSocket Service Architecture
Word Document Extraction
Workflow Agent Node Configuration
Workflow and Agent Composition
Workflow Conditional Branching
Workflow Container Nodes
Workflow Conversation State Management
Workflow Draft Synchronization
Workflow Execution Dispatch
Dify Agent Server 模块分析 (Commit 55f95dbc)
Workflow Execution Persistence
Workflow Fail Branch Architecture
Workflow File Handling
Workflow Graph Validation
Workflow Iteration Node Execution
Workflow LLM Node Configuration
Workflow Memory Management
Workflow Node Canvas Summary Rendering
Workflow Node Versioning
Workflow Pause-Resume State Management
Workflow Resume Architecture
Workflow Run State Management
Workflow Schedule Triggers
Workflow Test Run Execution
Workflow Timeout and Execution Limits
Workflow Tool Visibility and Access Control
Workflow Trigger Log Lifecycle
Workflow Variable Size Management