Agent V2 File and Vision Handling#

Agent V2 file and vision handling spans three concerns: a frontend gating layer that decides which files are included in the chat request, a backend forwarding path that encodes those files and injects them into the agent runtime, and configure UI awareness of the selected model's vision capabilities. Several bugs in each layer have been patched or have pending fixes.

Key files:

• app_generator.py — orchestrates generate, parses uploaded files into access-controlled Dify File objects
• runtime_request_builder.py — assembles the dify-agent run request, detects vision support, constructs multimodal or download layers
• request_builder.py — defines AgentBackendAgentAppRunInput and emits layer specs
• model_access.py — provides resolve_model_supports_vision() to inspect credential-bound model schemas
• layer.py — dify-agent user_prompt layer implementation for multimodal content
• chat-conversation.tsx — frontend send path; line 186 is the current vision-gate fix

File Forwarding Path#

When a user sends a message with attachments in an Agent App:

1. Frontend (chat-conversation.tsx) — files are unconditionally attached: if (files?.length) data.files = files.

2. app_generator.generate() reads args.get("files") into raw_files. Within a file-access scope, it calls file_factory.build_from_mappings() to parse uploaded files into access-controlled Dify File objects. These File objects are passed to _AgentAppRunner via AgentAppGenerateEntity with the populated files field (not empty). No file locators are appended to the query text anymore.

3. AgentAppRuntimeRequestBuilder.build() calls _build_user_files() to determine delivery mode. The builder invokes resolve_model_supports_vision() from core.app.llm.model_access to check if the selected model supports vision. When vision is supported and image files are present, images are converted to DifyUserPromptImageConfig and sent through the DifyUserPromptLayerConfig as native multimodal content. Image URLs become Pydantic AI ImageUrl content; inline Base64 images become BinaryContent. Non-image files and cases where vision is not supported fall back to the delivery="download" mode with shell-based dify-agent file download instructions appended to the prompt text.

4. dify-agent backend (layer.py) — the DifyUserPromptLayer consumes the DifyUserPromptLayerConfig. Images marked delivery="multimodal" are converted to Pydantic AI ImageUrl or BinaryContent and sent directly to the model. Files marked delivery="download" have their locators serialized and appended to the prompt text.

Known Gaps and Fixes#

All Attachments Dropped for Non-Vision Models — Fixed#

Previously, chat-conversation.tsx had if (files?.length && supportVision) data.files = files, gating all file types on the model's vision flag 6. DOCX, PDF, and TXT uploads were silently discarded whenever the selected model didn't advertise ModelFeature.VISION.

PR #40586 / #40179 (merged 2026-08-12) removed the && supportVision check. Vision capability governs whether the LLM can interpret images directly; it must not gate file delivery to the agent sandbox, where tools process documents independently of LLM vision support 7.

Vision Toggle Missing in Configure UI — Open#

The Agent V2 "Chat Features" panel renders a generic File Upload card with no ModelFeature.VISION check 8. The legacy agent configure, by contrast, reads currModel.features in use-configuration.ts and renders ConfigVision with resolution (high/low) controls. The confirmed gaps in Agent V2:

• No vision capability check anywhere in the configure context
• No warning or toggle when image uploads are enabled on a non-vision model
• image.detail resolution setting is buried in the generic file-upload settings modal, not surfaced as a top-level control

PR #41135 (OPEN) proposes threading supportsVision from useAgentConfigureModelOptions() into the configure context, adding a non-blocking warning banner for the mismatch case, and surfacing the resolution setting.

Initial File Forwarding — Fixed#

Before PR #37926 (merged 2026-06-25), the files field was always empty at execution time even when a file was visually accepted in the UI. The fix wired file handling through FileUploadConfigManager and file_factory in app_generator.py, and introduced the DifyUserPromptLayerConfig / DifyUserPromptFileConfig layer in dify-agent.

Images Sent as Download Instructions — Fixed#

PR #41685 (merged 2026-09-07) replaced the old prompt_file_mappings approach. Previously, all files (including images) were serialized as JSON locators and appended to the user prompt as text instructions for the agent's built-in download tools. The fix introduces:

• Vision detection via resolve_model_supports_vision() inspecting the credential-bound model schema
• Native multimodal delivery for images when the model supports vision
• The DifyUserPromptLayer in dify-agent converts image URLs to Pydantic AI ImageUrl and inline Base64 to BinaryContent
• Non-image files and non-vision models continue to use the download fallback

Vision Capability: Legacy vs Agent V2#

Related Topics#

• Agent File Handling — covers DifyAgentNode output normalization, ToolFile rebacker, and unsigned URL issues (workflow/pipeline path, distinct from Agent App chat input)
• Agent File Upload Configuration — covers AgentFileUploadFeatureConfig, file type buckets, and the allowed-types/methods model