# File Input

> Enable file uploads in FastGPT Chat Agents and Workflows to support document parsing, image understanding, and multimodal Q&A.

Source: https://doc.fastgpt.io/guide/build/general/fileInput
Last Updated: 2026-11-12

Starting from version 4.8.9, FastGPT supports configuring file uploads in both **Chat Agent (Simple Mode)** and **Workflows**. This guide covers how to use file input and explains the difference between document parsing and multimodal file handling.

## Using in Chat Agent (Simple Mode)

Chat Agent (Simple Mode) reads ordinary documents through its document-parsing path and uses their text in the conversation. Releases 4.8.9–4.8.12 let the model decide through tool calling; version 4.8.13 introduced the forced-parsing behavior described below.

Find the file upload option on the left panel and click the `Enable`/`Disable` toggle to open the configuration dialog.

![Enable file upload](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/current/file-upload-settings.png.webp)

Once enabled, a file selection icon appears in the chat input area. Click it to select files for upload.

![Enable file upload](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/current/file-input-attachment.png.webp)

**Behavior**

Starting from version 4.8.13, Chat Agent (Simple Mode) forces file parsing and merges the content into the corresponding user message so multi-turn conversations consistently reference uploaded documents.

## Using in Workflows

In Workflows, find the `File Upload` option in the system configuration panel and click the `Enable`/`Disable` toggle to open the configuration dialog.

![Enable file upload](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/current/file-upload-settings.png.webp)

Connect **Start → File URLs** to **Document Parse → Document URLs**, then pass the parsed text to AI Chat, content extraction, or HTTP nodes. Upload a TXT file, run the workflow, and check that the parsed output contains its content.

![Document parsing workflow and result](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/current/document-parse-result.png.webp)

![Document parsing inputs and outputs](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/current/document-parse-node.png.webp)

## How Document Parsing Works

FastGPT’s ordinary-document parsing path converts files to text before passing them to the model, while multimodal handling follows the selected model’s capabilities and file-input settings. The following four stages — storage structure, media routing, node concatenation, and prompt injection — explain how document parsing works:

### How are uploaded files stored in the database?

In FastGPT's chat history, messages with role=user store their value in this structure:

```ts
type UserChatItemValueItemType = {
  text?: {
    content: string;
  };
  file?: {
    type: 'image' | 'audio' | 'video' | 'document' | 'unknown'; // 'file' is kept only for legacy data
    name?: string;
    key?: string;
    url: string;
  };
};
```

Uploaded files are stored as URLs — parsed document content is not stored.

### How are images, audio, and video handled?

The document parsing node does not parse multimodal files such as images, audio, or video. These files should be handled by an LLM that supports the corresponding multimodal capability, with multimodal recognition enabled in [AI Settings](https://doc.fastgpt.io/guide/build/general/ai_settings).

In practice, file input has two different handling paths:

1. Document parsing: handles document files such as PDF, Word, Excel, Markdown, and HTML, converts their content to text, and provides that text to the AI.
2. Multimodal recognition: handles media files such as images, audio, and video. FastGPT converts them into model-readable input, and a model with the corresponding capability reads them.

### How does the document parsing node work?

The document parsing node accepts an `array<string>` input (file URLs) and outputs a `string` (the parsed content).

* The node only parses URLs with document-type file extensions. If you upload both documents and multimodal files, multimodal files are ignored.
* **The document parsing node only processes files from the current workflow run, not files from chat history.**
* How multiple documents are concatenated:

Multiple files are concatenated using the following template — filename + content, joined by `\n\n`:

```
## ${filename}
${content}
```

### How to pass File Links to the AI Chat node

In Workflows, the **AI Chat** node provides a **File Link** (called "Document Citation" in earlier versions) input port where you can select the **File Link** output from the **Start** node (or any string array of document URLs) to parse and cite documents directly.

It accepts an `Array<string>` input. The URLs are parsed and merged into the corresponding user message, with each file listed in a `<file>` block (`<sandboxPath>` is optional and `<content>` appears only when document text has been parsed). The prompt template is (the built-in text is in Chinese):

```
## 对话文件
用户本次对话上传的文件，用途：
1. 可通过 read_files 读取文档内容。
2. 可把 url 作为模型参数。

<file>
<name>${filename}</name>
<url>${fileUrl}</url>
<content>${content}</content>
</file>
```

## Changes to File Upload in Version 4.8.13

There are some differences from version 4.8.9. We've maintained backward compatibility to avoid breaking existing workflows, but please update your workflows to follow the new rules as soon as possible — compatibility code will be removed in future versions.

1. Chat Agent (Simple Mode) forces file parsing and injects document content into the prompt, ensuring documents are always referenced.
2. Document parsing: no longer parses files from chat history.
3. AI Chat node: supports selecting **File Link** from the **Start** node directly in the **File Link** (formerly "Document Citation") input port, and automatically parses files from chat history.
4. Standalone plugin execution: plugin inputs support file-type configuration for receiving uploaded files.
5. **Workflow calling plugins: bind the file URL variable explicitly to the plugin input.**
6. **Workflow calling sub-workflows: manually select which file URLs to pass to the sub-workflow.**
