Workflow and Agent Composition#

Dify allows Workflow-type apps to be published as reusable tools that other workflows or agents can invoke. This is implemented through the ToolProviderType.WORKFLOW provider family, which lives under api/core/tools/workflow_as_tool/. The two core files are:

• tool.py — the WorkflowTool class (the actual callable)
• provider.py — the WorkflowToolProviderController that builds and vends WorkflowTool instances

Within Agent V2 nodes, the WorkflowAgentDifyToolsBuilder in api/core/workflow/nodes/agent_v2/dify_tools_builder.py is responsible for resolving all configured Dify tools—including WORKFLOW providers—into the layer configs the Agent backend consumes.

WorkflowTool: How Invocation Works#

WorkflowTool extends Tool and reports ToolProviderType.WORKFLOW 1. Its _invoke method:

1. Resolves the target App and Workflow records from the database 2.
2. Transforms tool parameters (including file handling) via _transform_args 3.
3. Delegates execution to WorkflowAppGenerator.generate() with streaming=False and call_depth + 1 4. This is what enforces the recursive depth limit.
4. Raises ToolInvokeError on workflow errors; otherwise yields variable, file, text, and JSON messages from the workflow outputs 5.

Key constraint: The tool explicitly sets pause_state_config=None, meaning workflow-level pausing mechanisms (e.g., HumanInput nodes) are not supported when a workflow runs as a tool 6. This is separately enforced at publish time by WorkflowToolConfigurationUtils.ensure_no_human_input_nodes.

The tool also carries trace context: set_parent_trace_context and set_trace_session_id attach outer workflow run identifiers for observability without exposing them as LLM-visible parameters 7.

WorkflowToolProviderController: Building the Tool#

WorkflowToolProviderController is constructed from a WorkflowToolProvider DB record via from_db(). The controller:

• Maps workflow input variable types to ToolParameter types via VARIABLE_TO_PARAMETER_TYPE_MAPPING 8. Supported types include TEXT_INPUT, PARAGRAPH, SELECT, NUMBER, CHECKBOX, FILE, FILE_LIST, and JSON_OBJECT.
• Derives an output_schema from the workflow's End node outputs 9. Reserved output keys (json, text, files) are excluded from the schema.
• Initializes WorkflowTool with workflow_call_depth=0, indicating this is the outermost invocation layer 10.

The WorkflowToolProvider model (in api/models/tools.py) stores: app_id, version (the published workflow version), name, label, icon, description, parameter_configuration, tenant_id, and user_id.

ToolManager integration: ToolManager.get_tool_runtime handles ToolProviderType.WORKFLOW by querying WorkflowToolProvider, converting it via ToolTransformService.workflow_provider_to_controller, and forking a WorkflowTool with an empty credentials dict 11. The ToolProviderType.APP case (for Agent-type app invocation) raises NotImplementedError 12.

Workflows as Tools in Agent V2 Nodes#

When an Agent V2 node runs, WorkflowAgentDifyToolsBuilder.build_layers() resolves all enabled Dify tools from AgentSoulToolsConfig into two layer configs for the Agent backend:

• plugin_tools (DifyPluginToolsLayerConfig) — for PLUGIN provider types (routed to the Plugin Daemon)
• core_tools (DifyCoreToolsLayerConfig) — for BUILT_IN, API, WORKFLOW, and MCP providers

WORKFLOW tools are routed to core_tools 13, which means tool invocations are delegated to POST /inner/api/agent/tools/invoke inside the API process rather than the plugin daemon. This keeps workflow credentials and state within the API boundary.

Provider-level entries (where tool_name is omitted) are expanded to individual tool entries via _expand_provider_entries 14, which calls WorkflowToolProviderController.from_db to enumerate declared tool names.

The builder's _fetch_tool_runtime wraps ToolManager.get_agent_tool_runtime and maps ToolProviderNotFoundError and ToolProviderCredentialValidationError to typed WorkflowAgentDifyToolsBuildError codes (agent_tool_declaration_not_found, agent_tool_credential_invalid) 15.

Tool configuration in Agent Soul uses AgentSoulDifyToolConfig, where builtin/api/workflow/mcp providers route through dify.core.tools 16.

Architectural Constraints and Known Limitations#

Only published, versioned workflows can be used as tools. WorkflowTool._get_workflow rejects draft workflows 17. Attempting to invoke an unpublished workflow raises ValueError: "workflow not found or not published".

Agent-type apps cannot be invoked as tools. ToolProviderType.APP is unimplemented in ToolManager.get_tool_runtime 12. A feature request to allow private, unpublished Agent apps to be called from within a workflow as internal sub-modules remains open 18. Note: this limitation applies to the legacy APP provider type; Agent V2 nodes have their own separate execution path via WorkflowAgentDifyToolsBuilder and the Agent backend.

HumanInput nodes are blocked. Publishing a workflow as a tool will fail with WorkflowToolHumanInputNotSupportedError if the workflow contains HumanInput nodes. Even if bypassed, WorkflowTool._invoke passes pause_state_config=None, dropping any pause semantics at runtime 6.

No referential integrity on deletion. If a workflow published as a tool is deleted, other workflows referencing it will fail silently at runtime. An open issue tracks adding strict reference validation before deletion is allowed 19.

Recursive depth tracking. WorkflowTool increments call_depth by 1 on each invocation 20. The maximum call depth is enforced by WorkflowAppGenerator.