From d8ba5b823a82cb0e7da310dc0b23dfe396f0691f Mon Sep 17 00:00:00 2001
From: Alex <alex@crewai.com>
Date: Fri, 27 Mar 2026 00:45:31 -0700
Subject: [PATCH] docs: add file upload support documentation for flows

- Add 'File Inputs' section to flows.mdx documenting:
  - Using crewai-files types (ImageFile, PDFFile, etc.) in flow state
  - CrewAI Platform (AMP) automatic file upload dropzone rendering
  - API usage with URL string coercion via Pydantic
- Update files.mdx with:
  - Example of file types in flow state
  - Note about CrewAI Platform integration for flows

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/en/concepts/files.mdx | 23 ++++++++++++++
 docs/en/concepts/flows.mdx | 63 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)

diff --git a/docs/en/concepts/files.mdx b/docs/en/concepts/files.mdx
index af86baabe..d260fe090 100644
--- a/docs/en/concepts/files.mdx
+++ b/docs/en/concepts/files.mdx
@@ -134,6 +134,29 @@ result = flow.kickoff(
 )
 ```
 
+You can also define file types directly in your flow state for structured file handling:
+
+```python
+from pydantic import BaseModel
+from crewai.flow.flow import Flow, start
+from crewai_files import ImageFile, PDFFile
+
+class DocumentState(BaseModel):
+    document: PDFFile
+    cover_image: ImageFile
+    title: str = ""
+
+class DocumentFlow(Flow[DocumentState]):
+    @start()
+    def process(self):
+        content = self.state.document.read()
+        return {"processed": True}
+```
+
+<Note type="info" title="CrewAI Platform Integration">
+When deploying flows to the CrewAI Platform (AMP), file fields in your state automatically render as file upload dropzones in the UI. For API usage, you can pass URL strings directly and Pydantic coerces them to file objects automatically. See [Flows - File Inputs](/en/concepts/flows#file-inputs) for details.
+</Note>
+
 ### With Standalone Agents
 
 Pass files directly to agent kickoff:
diff --git a/docs/en/concepts/flows.mdx b/docs/en/concepts/flows.mdx
index defbd3e01..6adbc07c2 100644
--- a/docs/en/concepts/flows.mdx
+++ b/docs/en/concepts/flows.mdx
@@ -341,6 +341,69 @@ flow.kickoff()
 
 By providing both unstructured and structured state management options, CrewAI Flows empowers developers to build AI workflows that are both flexible and robust, catering to a wide range of application requirements.
 
+## File Inputs
+
+Flows support file inputs through the `crewai-files` package, enabling you to build workflows that process images, PDFs, and other file types. When you use file types like `ImageFile` or `PDFFile` in your flow state, they integrate seamlessly with both local development and the CrewAI Platform.
+
+<Note type="info" title="Optional Dependency">
+File support requires the optional `crewai-files` package. Install it with:
+
+```bash
+uv add 'crewai[file-processing]'
+```
+</Note>
+
+### Using File Types in Flow State
+
+You can include file types directly in your structured flow state:
+
+```python
+from pydantic import BaseModel
+from crewai.flow.flow import Flow, start
+from crewai_files import ImageFile, PDFFile
+
+class DocumentProcessingState(BaseModel):
+    document: PDFFile        # Renders as file upload in CrewAI Platform
+    cover_image: ImageFile   # Renders as image upload
+    title: str = ""          # Renders as text input
+
+class DocumentFlow(Flow[DocumentProcessingState]):
+    @start()
+    def process_document(self):
+        # Access the file - works with URLs, paths, or uploaded files
+        content = self.state.document.read()
+        # Or pass to an agent with VisionTool, etc.
+        return {"processed": True}
+```
+
+### CrewAI Platform Integration
+
+When you deploy a flow to the CrewAI Platform (AMP), file fields in your state automatically render as file upload dropzones in the UI. This makes it easy to build user-facing applications that accept file uploads without any additional frontend work.
+
+| State Field Type | Platform UI Rendering |
+|:-----------------|:----------------------|
+| `ImageFile` | Image upload dropzone |
+| `PDFFile` | PDF upload dropzone |
+| `AudioFile` | Audio upload dropzone |
+| `VideoFile` | Video upload dropzone |
+| `TextFile` | Text file upload dropzone |
+| `str`, `int`, etc. | Standard form inputs |
+
+### API Usage
+
+When calling your flow via API, you can pass URL strings directly for file fields. Pydantic automatically coerces URLs into the appropriate file type:
+
+```python
+# API request body - URLs are automatically converted to file objects
+{
+    "document": "https://example.com/report.pdf",
+    "cover_image": "https://example.com/cover.png",
+    "title": "Q4 Report"
+}
+```
+
+For more details on file types, sources, and provider support, see the [Files documentation](/en/concepts/files).
+
 ## Flow Persistence
 
 The @persist decorator enables automatic state persistence in CrewAI Flows, allowing you to maintain flow state across restarts or different workflow executions. This decorator can be applied at either the class level or method level, providing flexibility in how you manage state persistence.