Workflow Agent Node Configuration#

A Workflow Agent Node (type agent, version 2) embeds an Agent V2 execution unit inside a Dify workflow graph. Its configuration is split across two persisted objects:

• Agent Soul (AgentSoulConfig) — the agent's identity: model, prompt, tools, knowledge, environment, and sandbox. Stored as a JSON snapshot in AgentConfigSnapshot.config_snapshot.
• Node Job (WorkflowNodeJobConfig) — workflow-specific wiring: declared outputs, previous-node output refs, human contacts, and task prompt. Stored in WorkflowAgentNodeBinding.node_job_config.

This separation means the same Agent Soul can be reused across multiple workflow nodes (Roster agents), while each node carries its own workflow wiring independently.

Key source files:

Validation: Draft vs. Publish#

WorkflowAgentNodeValidator has two entry points with different strictness levels:

• validate_draft_workflow — iterates all Agent v2 nodes in the graph, validates the node schema via DifyAgentNodeData.model_validate, and checks any existing binding. A missing binding is silently skipped (the node is unconfigured but not yet in error). 1
• validate_published_workflow — same checks, but a missing binding is a hard error. It also validates graph topology (upstream relationships for previous-node output refs). 2

Agent v2 nodes are identified by three conditions:

• node_data.type == BuiltinNodeTypes.AGENT
• node_data.version == "2"
• node_data.agent_node_kind == "dify_agent"

The three-part check is encapsulated in is_dify_agent_node_data. Historical Agent nodes with type=agent, version=2 but without the agent_node_kind marker are routed back to the legacy Agent implementation for backward compatibility. 3

Binding Validation#

validate_binding accepts an optional require_agent_model: bool = True parameter that controls whether the agent soul model configuration is required (True for publish validation, False for draft validation). It runs these checks in order:

1. Agent existence — the bound Agent row must exist, be in the correct scope (ROSTER vs. inline), and not be archived. 4
2. Snapshot existence — the active AgentConfigSnapshot must exist for the resolved snapshot ID. 5
3. Model presence — AgentSoulConfig.model must not be None when validating published workflows (controlled by the require_agent_model parameter). Draft workflow validation allows model-less inline Agent nodes to support incremental configuration. Raises WorkflowAgentNodeValidationError if missing when required. 6
4. Environment variables — agent-level and CLI tool env names must be unique and all secret refs must have an authorized permission status. 7
5. Tools — enabled Dify tool names must be unique; enabled CLI tools must be pre-authorized, have no denied permissions, and acknowledge dangerous commands. 8
6. Knowledge datasets — all referenced dataset IDs must exist within the tenant. 9

Node Job Validation#

validate_node_job checks:

• Locked soul fields — the node_job.metadata must not contain any key from _LOCKED_AGENT_SOUL_KEYS (e.g., agent_soul, tools, model). This prevents the node job from overriding soul-owned configuration. 10 11
• Duplicate output names — declared outputs must have unique names. 12
• Reserved output names — custom outputs cannot use reserved names (text, switch, _session). These are defined in RESERVED_DECLARED_OUTPUT_NAMES.
• File refs — benchmark file refs on output checks must be resolvable UploadFile rows within the same tenant. 13
• Previous-node output refs — each ref must resolve to a valid [node_id, output_name] selector, and at publish time, the source node must exist upstream of the agent node in graph topology. 14
• Human contact refs — each human contact must have a valid contact_id and an allowed channel. 15

Tool Node Agentic Mode (Publish-time)#

At publish time, the validator also checks all Tool nodes in the graph. If a tool node has an agentic_mode config, it must be complete, authorized, and either in a manual state or have an inferred parameter draft. 16

Runtime: Tool Layer Construction#

When a run starts, WorkflowAgentDifyToolsBuilder.build_layers translates the AgentSoulToolsConfig into two Agent backend layer configs:

• DifyPluginToolsLayerConfig — for PLUGIN provider types (routed to Plugin Daemon)
• DifyCoreToolsLayerConfig — for BUILT_IN, API, WORKFLOW, and MCP providers (routed to internal API at POST /inner/api/agent/tools/invoke)

The builder follows these steps per tool:

1. Provider expansion — if tool_name is None (provider-level entry = "all tools"), _expand_provider_entries queries the provider for its declared tool names (via ToolManager, WorkflowToolProviderController, or MCPToolManageService) and emits one entry per tool. Already-explicit tool names are skipped to avoid duplication.

2. MCP normalization — MCP provider IDs are resolved to their runtime server identifiers via _resolve_mcp_provider_id. 17

3. Tool runtime fetch — _fetch_tool_runtime calls ToolManager.get_agent_tool_runtime. Errors map to stable WorkflowAgentDifyToolsBuildError codes:

   • agent_tool_declaration_not_found — provider or tool not found
   • agent_tool_credential_invalid — credential validation failed
   • agent_tool_config_invalid — other ValueError during runtime construction

4. Required parameter check — _runtime_parameters checks that every non-LLM, required parameter with no default has a value in runtime_parameters. Missing ones raise agent_tool_runtime_parameter_missing.

   Note: This is the source of the "tool parameter {name} not found in tool config" error seen in issue #15468. The lower-level init_frontend_parameter in parameters.py raises a ValueError when a required parameter (e.g., instruction) has no value and no default. This propagates up through the tool initialization chain.

5. Plugin JSON schema augmentation — _plugin_parameters_json_schema patches FILE and FILES-typed LLM parameters into the schema using a anyOf shape that accepts URL strings or {transfer_method, url/reference} objects.

6. Credential normalization — only scalar values (str, int, float, bool, None) are forwarded to the Plugin Daemon; non-scalar credential values raise agent_tool_credential_shape_invalid. 18

Runtime: Request Assembly#

WorkflowAgentRuntimeRequestBuilder.build assembles the final CreateRunRequest sent to the Agent backend:

1. Validates the soul model config is present (raises agent_model_not_configured if not). 19
2. Calls build_layers to produce tool layer configs; maps WorkflowAgentDifyToolsBuildError to WorkflowAgentRuntimeRequestBuildError. 20
3. Builds prompts:
   • Soul prompt — from agent_soul.prompt.system_prompt with prompt-mention resolution (skills, files). 21
   • Workflow task prompt — from node_job.workflow_prompt with mention resolution. Stale previous_node_output_refs not referenced in the current prompt are discarded. 22
   • Workflow context prompt — assembles sys.query, sys.files, and resolved previous-node output values. 23
4. Builds structured output schema from node_job.declared_outputs — the structured-output layer is only used when custom outputs are configured. Without custom outputs, the backend uses a plain string contract and the Agent backend output layer is omitted entirely. For structured runs, a system-owned text output is prepended to custom declarations at runtime (not persisted). 24
5. Builds knowledge, shell, ask-human, and execution-context layer configs from agent soul fields. 25
6. Assigns an idempotency key scoped to (workflow_run_id, node_execution_id, attempt) so retries get distinct keys. 26

Output Normalization#

The output contract differs for plain and structured runs:

• Plain runs (no custom outputs) — the backend produces a free-form string, which is mapped directly to the system text output. The structured-output layer is omitted.
• Structured runs (custom outputs configured) — the system text output is prepended to custom declarations. The text field is optional and free-form; only custom fields undergo type checking, retry/default handling, and file normalization.
• File normalization — only structured runs with declared FILE or ARRAY[FILE] fields undergo file normalization. The WorkflowAgentOutputAdapter converts canonical file mappings into FileSegment values for those declared fields.

The effective output projection is implemented by effective_declared_outputs in api/models/agent_config_entities.py. This function prepends the system text output from SYSTEM_DECLARED_OUTPUTS to the custom declarations. The system output is:

• Name: text
• Type: STRING
• Required: false
• Description: "Free-form text answer."

The constant SYSTEM_DECLARED_OUTPUTS replaces the former DEFAULT_DECLARED_OUTPUTS, which included preset files and json outputs. Those preset outputs have been removed, and users may now define custom fields named files or json without conflict.

Stale Tool Parameters#

When a tool is removed from the Agent Soul config, its saved runtime_parameters entries in AgentSoulDifyToolConfig are simply absent from the enabled tool list. build_layers only processes tools where tool.enabled == True, so orphaned parameter entries for removed tools are implicitly dropped — they are never forwarded to the Agent backend. 27

However, if a tool is re-added with changed parameter definitions, any previously stored runtime_parameters that no longer match declared parameters will surface as agent_tool_runtime_parameter_missing errors at runtime if a now-required parameter is absent. The fix is to update the tool's stored runtime_parameters in the Agent Soul config via the Composer UI.