Agent File Upload Configuration#

Overview#

Agent file upload configuration controls which files users can attach to conversations with an Agent V2 app. It lives inside AgentSoulAppFeaturesConfig as the file_upload field 1 and is stored as part of the versioned AgentSoulConfig JSON snapshot. Changes take effect only on publish; the runtime validates the snapshot before any LLM call is made.

Configuration Model#

AgentFileUploadFeatureConfig (Pydantic model, api/models/agent_config_entities.py) defines all upload policy fields:

FileType and FileTransferMethod are enums from the graphon library 2.

Semantic File Type Buckets#

FileType groups files into four semantic categories: DOCUMENT, IMAGE, AUDIO, VIDEO, plus a catch-all CUSTOM bucket. allowed_file_types controls which categories are accepted. The CUSTOM bucket is the escape hatch — when it is included, validation falls through to the allowed_file_extensions whitelist.

The UI surfaces the same five categories 3:

audio | custom | document | image | video

Custom Extension Whitelisting#

When a file's type does not match any category in allowed_file_types, or the type is explicitly CUSTOM, the allowed_file_extensions list is the sole gate 4.

Rules enforced by is_file_valid_with_config():

• Extension comparison is case- and dot-insensitive via _normalize_extension().
• An empty whitelist ([]) denies all files in the custom bucket. The UI never submits an empty list, but this guards DSL/API paths that bypass the UI 4.
• If allowed_file_extensions is None (not set), the extension check is skipped entirely.

Validation Logic#

is_file_valid_with_config() is invoked after a File object is built from a mapping, if a FileUploadConfig is present. The four-step check:

1. Tool files bypass validation — TOOL_FILE transfer method always passes 5.
2. Type allowlist — file type must be in allowed_file_types, or CUSTOM must be present 6.
3. Extension whitelist (CUSTOM bucket) — enforces allowed_file_extensions when the file falls into the custom bucket 4.
4. Transfer method — IMAGE files check image_config.transfer_methods; all others check allowed_file_upload_methods 7.

Agent-Configured Files vs. Message Attachments#

There are two distinct file contexts in an agent conversation:

Agent-configured files (persistent)#

Files uploaded by the agent builder into the agent's configuration — analogous to pre-loaded context. They follow a two-step commit: first uploaded via POST /files/upload, then committed to the agent config version via POST /agent/{agent_id}/config/files 8. The agent-server fetches them at runtime through a two-step flow: first, it requests download metadata from the inner-API endpoint POST /agent-config/{agent_id}/download-request, which validates authorization and returns a short-lived, origin-free /files/* URI; then the agent-server fetches the file bytes directly from the Dify API data plane using that URI 9. This unified endpoint handles both file and skill downloads. These files persist across all conversations for that agent version.

Message attachments (conversation-scoped)#

Files attached by end-users during a conversation turn. They are validated against FileUploadConfig at upload time. Once stored in message history, they are not re-validated on replay — re-validation would break history whenever the agent's upload config drifts between configuration versions.

Frontend Integration#

chat-features-panel.tsx converts between the generic Features['file'] type (shared feature panel UI) and AgentSoulAppFeaturesConfig['file_upload']. chat-config.ts collapses the agent config's file_upload into the legacy ChatConfig['file_upload'] shape for the preview — falling back to SupportUploadFileTypes.image if allowed_file_types is empty, and defaulting number_limits to 3 10.

Size Limits#

Per-type size limits are enforced at upload time by FileService.is_file_size_within_limit(), routing to the appropriate config variable (UPLOAD_IMAGE_FILE_SIZE_LIMIT, UPLOAD_VIDEO_FILE_SIZE_LIMIT, UPLOAD_AUDIO_FILE_SIZE_LIMIT, UPLOAD_FILE_SIZE_LIMIT) based on the file extension. The upload dialog surfaces these limits via useFileUploadConfig() and useFileSizeLimit() 11.

Key Source Files#