Agent File Handling#

Agent file handling in Dify covers how the DifyAgentNode (agent v2) manages file data across three phases:

1. Input propagation — forwarding user-uploaded or workflow-injected files to the agent backend runtime
2. Output normalization — converting raw backend payloads into typed FileSegment / ArrayFileSegment values
3. Post-run validation & failure orchestration — type-checking declared file outputs and deciding whether to retry, apply defaults, or fail

All relevant server-side code lives under api/core/workflow/nodes/agent_v2/ 1:

The agent backend runtime (dify-agent) handles file parameters for plugin tools in dify-agent/src/dify_agent/layers/dify_plugin/tools_layer.py 2.

Runtime File Propagation (Inputs)#

Two separate input file paths feed the agent backend, both of which had gaps patched in recent releases 1:

• Chat-uploaded files (Agent App mode): PR #37926 added user_files to AgentBackendAgentAppRunInput and routes them through a DifyUserPromptLayerConfig, so files reach the backend as BinaryContent. Before this fix, the files parameter was empty at execution time even when a file was visually accepted in the UI.

• Workflow sys.files (Workflow/Chatflow mode): PR #38453 added _summarize_uploaded_workflow_files() in runtime_request_builder.py, which reads SystemVariableKey.FILES from the variable pool and injects them into the workflow context prompt. The early-return condition was also relaxed so the context is populated whenever uploaded files are present, even without an explicit user query text.

File access control: DatabaseFileAccessController checks that the created_by field on an uploaded file matches the user_id in the execution context. A mismatch causes a silent None return — the file is silently dropped from the files list 3. Ensure the same user identifier is used for both the file upload and the subsequent agent invocation.

Exception — in-run tool files: ToolFile records produced during the current workflow execution (e.g., by a tool or plugin node) are automatically granted access via grant_tool_file_access(), allowing them to be passed to later nodes even when their user_id differs from the end-user scope [PR #41300]. This specifically fixes the scenario where a workflow downloads or produces a file in one tool node and passes it to a later LLM vision node. When such a workflow is published and invoked as a tool from an agent under an end-user scope, the tool-produced files remain accessible across nodes within the same execution context. Files that are not granted during execution (e.g., files from external uploads or different executions) still require matching user_id.

Output Normalization#

WorkflowAgentOutputAdapter converts the terminal AgentBackendRunSucceededInternalEvent payload into a NodeRunResult. File normalization happens in _normalize_outputs(), which processes each key in the backend output dict and applies type-aware conversion only for fields declared as FILE or ARRAY[FILE] 1.

Three code paths handle file values:

1. Already a File/FileSegment/ArrayFileSegment — passed through unchanged.
2. Legacy {"id": "<tool_file_id>"} — _normalize_legacy_tool_file_value() calls the injected ToolFileRebacker to hydrate the file from the ToolFile DB row. Older agent backend builds may return this format.
3. Canonical declared mapping (tool_file, local_file, datasource_file) — _normalize_declared_output_value() calls build_from_mapping() with the resolved tenant_id. A remote_url mapping only requires {"transfer_method": "remote_url", "url": "..."} with no tenant_id needed. For persisted transfer methods, tenant_id is mandatory — the adapter raises ValueError if it is missing.

tenant_id is resolved from either the call-site parameter or metadata["tenant_id"] set during backend run setup. The ToolFileRebacker is defined as a Protocol, making it injectable for testing.

ToolFile Rebacker#

reback_tool_file_output() in output_file_rebacker.py provides backwards-compatibility for agent backends that return output files as bare {"id": "<uuid>"} mappings instead of full canonical references 1.

The function:

• Validates the UUID format and enforces tenant ownership (ToolFile.tenant_id == tenant_id); returns None on any mismatch rather than fabricating a file with empty metadata.
• Derives mime_type, extension, and size from the ToolFile DB row — the sandbox payload is never trusted for metadata.
• Produces a File with transfer_method=TOOL_FILE and a canonical dify-file-ref:… reference built via build_file_reference().

This component was introduced as part of the Agent Files infrastructure in PR #37172 4.

Output Type Checking & Failure Orchestration#

After a successful backend run, DifyAgentNode runs a per-output type check before constructing the final NodeRunResult 1.

Type Checker (output_type_checker.py) validates:

• The raw output is a JSON dict; if not, all declared outputs fail.
• Each declared FILE field has a valid canonical dify-file-ref:… reference and a matching transfer method with tenant access verified.
• Each element in ARRAY[FILE] fields is validated individually.

The JSON schema transmitted to the agent backend was progressively tightened:

• PR #38183 introduced AgentStubFileMapping to replace manual oneOf construction 5.
• PR #38221 added additionalProperties: false and a regex constraint on canonical references to prevent agents from inventing references 6.

Failure Orchestrator (output_failure_orchestrator.py) determines what happens when type-check fails:

The retry budget is the maximum across all failing outputs. When exhausted, the orchestrator merges per-output terminal strategies using precedence: FAIL_BRANCH > STOP > DEFAULT_VALUE. Defaults are patched into the event output via _patch_event_with_defaults() before the output adapter runs 1.

Plugin Tool File Transport (dify-agent)#

The agent backend runtime (dify-agent) handles FILE and FILES-typed plugin tool parameters in tools_layer.py 2.

_PluginToolFileContext resolves file inputs before tool invocation via three paths 7:

• Remote URL string — passed through as-is (requires http:// or https:// prefix).
• Sandbox path string — uploaded to Dify via a shell script calling dify-agent file upload; returns a tool_file mapping with a canonical reference.
• File mapping dict — for remote_url transfer method, URL is used directly; for local_file, tool_file, or datasource_file, calls POST /inner/api/download/file/request to get a signed download URL.

_cast_tool_parameter_value() handles the type dispatch 8:

• FILE — resolves a single file via to_plugin_file_parameter() (raises if a list with ≠ 1 element is supplied).
• FILES / SYSTEM_FILES — maps to_plugin_file_parameter() over each list item.

All resolved files are normalized into {"dify_model_identity": "__dify__file__", "type": ..., "url": ...} dicts before being sent to the plugin daemon 9.

Tool response handling: _convert_tool_response_to_text() collapses daemon stream messages into a plain-text observation 10. IMAGE and IMAGE_LINK messages currently produce a static string ("image has been created and sent to user already…") — the image URL is not forwarded. See Known Issues.

Canonical File Reference Format#

All persisted file references in agent v2 contracts use the opaque format dify-file-ref:<base64url-json>, implemented in api/core/workflow/file_reference.py 11.

The type checker enforces canonical format on new agent outputs. Legacy raw record IDs are only tolerated through the rebacker path for older backend builds 1.

Known Issues#

Tool-Generated Images Dropped in Agent App (open)#

PR #40455 (open) addresses two loss layers in the Agent App path 12:

1. _convert_tool_response_to_text discards the URL carried in IMAGE/IMAGE_LINK daemon messages.
2. AgentAppRunner/_AgentProcessRecorder has no equivalent of the legacy ToolFileMessageTransformer → ToolEngine._create_message_files → QueueMessageFileEvent chain.

The proposed fix: the SDK reports URL-bearing image references on ToolReturnPart.metadata under the dify_tool_files key; the API side replays the legacy chain to create MessageFile rows and publish QueueMessageFileEvent, which feeds the existing SSE stream without frontend changes. Failures degrade gracefully to the text-only observation. The workflow agent v2 node path also loses images, but exposing them there requires file-typed node outputs (separate feature). As of the current date this PR is not yet merged 12.

Unsigned Tool File URLs → 422/403 Errors#

base_app_runner.py stores /files/tools/{id} as a bare unsigned path in MessageFile.url 13. Separately, ToolFileMessageTransformer.get_tool_file_url() returns /files/tools/{tool_file_id}{extension} unsigned. The /files/tools/ endpoint validates timestamp, nonce, and sign query parameters and rejects requests without them (422 Unprocessable Entity if missing/invalid; 403 Forbidden on signature verification failures).

The intended two-stage pattern: URLs are stored unsigned early, then message_file_utils.py calls sign_tool_file() at serialization time. Code paths that bypass message_file_utils.py expose unsigned URLs. The signing entry points are in api/core/tools/signature.py 13.

Agent Squid Proxy Blocking External File Domains#

When INTERNAL_FILES_URL is set to an empty string in Docker, the previous AliasChoices lookup selected the empty value instead of falling back to SERVER_CONSOLE_API_URL. Agent file URLs then resolved to the external hostname, which the agent Squid proxy blocked if it mapped to a private IP. Fixed (PR #39839): resolution order is now INTERNAL_FILES_URL → SERVER_CONSOLE_API_URL → FILES_URL, with the resolved file origin passed to agent_ssrf_proxy as a Squid exception 1.

File Disappears Due to User Identity Mismatch#

If the user identifier used for a file upload differs from the one used in the subsequent agent invocation, DatabaseFileAccessController silently returns None and the file is dropped 3. This is not agent-v2-specific — it affects any Dify app type. Ensure the same user value is used consistently across upload and invocation API calls.

Fixed for in-run tool files: ToolFile records produced during a workflow execution (e.g., by tool or plugin nodes) are automatically granted access via grant_tool_file_access() [PR #41300]. This allows workflow-as-tool scenarios where a file is downloaded/produced in one node and passed to a later LLM vision node, even when the published workflow is invoked from an agent under a different end-user scope. Files that are not granted during execution (external uploads, files from different executions) still require matching user_id.