---
schema_version: "1"
id: 9f6afb400f2128142be52607b0da90ec27406e4195367bf587aaf602cc2e9b39
title: Set Up File Uploads for an Agent
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/ai/264-0-0/agent_file_upload_configure.md
canonical_url: https://help.salesforce.com/s/articleView?id=ai.agent_file_upload_configure.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: 654dd716b9d02d797adc38b50ca72e0497c891a4c9d1b90e8dff8adc82bb5b19
description: Add file upload support to your agent, so your users can share screenshots, receipts, and PDFs. Your agent can interpret individual files or a group of files, answer questions based on one or more files, and add files to a Salesforce record.
products:
  - Agentforce
  - Cross Cloud
release: "264"
---
# Set Up File Uploads for an Agent

Add file upload support to your agent, so your users can share screenshots, receipts, and PDFs. Your agent can interpret individual files or a group of files, answer questions based on one or more files, and add files to a Salesforce record.

### Required Editions

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small edition"><colgroup><col></colgroup><tbody><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: Lightning Experience</td></tr><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: <strong>Enterprise</strong>, <strong>Performance</strong>, <strong>Unlimited</strong>, and <strong>Developer</strong> Editions. <a href="https://help.salesforce.com/s/articleView?id=ai.agent_setup_explore_types.htm&amp;release=264.0.0&amp;type=5" title="Learn about agent types and default templates for specific clouds and common use cases.">Required add-on licenses vary by agent type.</a></td></tr></tbody></table>

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small permission">
        <colgroup>
          <col style="width:50%">
          <col style="width:50%">
        </colgroup>
        <thead class="slds-text-title_caps ">
          <tr class="">
            <th scope="colgroup" class="slds-cell-wrap" colspan="2" style="vertical-align:top;" id="d25566e78">User Permissions Needed</th>
          </tr>
        </thead>
        <tbody>
          <tr class="">
            <td data-label="User Permissions Needed" class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e78 ">To set up file uploads in an AI agent:</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e78 ">Manage AI Agents AND <a href="https://help.salesforce.com/s/articleView?id=ai.agent_setup_explore_types.htm&amp;type=5&amp;language=en_US" target="_blank">the required permissions for your agent
                type</a></td>

          </tr>
        </tbody>
      </table> <table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small ">
        <colgroup>
          <col style="width:20%">
          <col style="width:80%">
        </colgroup>
        <thead class="slds-text-title_caps ">
          <tr class="">
            <th scope="colgroup" class="slds-cell-wrap" colspan="2" style="vertical-align:top;" id="d25566e112">Agentforce File Upload Support</th>
          </tr>
        </thead>
        <tbody>
          <tr class="">
            <td data-label="Agentforce File Upload Support" class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e112 ">Agent Types</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e112 ">
              <p>Agentforce Service agents, Agentforce Employee agents</p>
              <p style="margin-bottom:0;">Agents must be created in or upgraded to Agent Script and Agentforce Builder in
                Agentforce Studio.</p>
            </td>

          </tr>
          <tr class="">
            <td data-label="Agentforce File Upload Support" class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e112 ">Channels</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e112 ">
              <p>Enhanced In-App Chat, Enhanced Web Chat v1, Enhanced Web Chat v2, Enhanced
                WhatsApp, Enhanced Facebook Messenger, Standard and Enhanced SMS, Enhanced Apple
                Messages for Business, Enhanced LINE, and Bring Your Own Channel</p>
              <p>The Salesforce mobile app isn't currently supported.</p>
              <p style="margin-bottom:0;">On LINE, WeChat, and WhatsApp, multiple attachments are split into individual
                messages and are processed by the agent individually. Text and images can also be
                sent to the agent as separate messages.</p>
            </td>

          </tr>
          <tr class="">
            <td data-label="Agentforce File Upload Support" class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e112 ">Models</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e112 ">
              <p>OpenAI GPT 4.1 only. Azure OpenAI isn’t currently supported. <a href="https://help.salesforce.com/s/articleView?id=ai.generative_ai_llm_multimodal_support.htm&amp;release=264.0.0&amp;type=5" title="Salesforce-managed models have different levels of support and limits for including JPG, PNG, or PDF files in a model request.">LLM Multimodal
                  Support limits</a> apply.</p>
              <p style="margin-bottom:0;">The HyperClassifier model doesn’t support images. <a href="https://help.salesforce.com/s/articleView?id=ai.agent_topics_routing.htm&amp;release=264.0.0&amp;type=5" title="Learn more about the Agent Router and how to customize it to control how your agent selects subagents in a conversation.">If you use the HyperClassifier
                  model for subagent classification</a>, you can’t use the Agent Router to file
                uploads or route conversations based on the content of file uploads.</p>
            </td>

          </tr>
          <tr class="">
            <td data-label="Agentforce File Upload Support" class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e112 ">Files</td>

            <td class="slds-cell-wrap" style="vertical-align:top;" headers="d25566e112 ">
              <p>PNG, JPEG, PDF</p>
              <p>Files can be up to 5 MB each.</p>
              <p style="margin-bottom:0;">An agent can accept up to 5 files per message (varies by channel) and up to 10
                files per conversation. If a user uploads more than 10 files, the agent saves the
                most recent 10.</p>
            </td>

          </tr>
        </tbody>
      </table>

Prerequisite: Data 360

Before you begin, make sure Data 360 is enabled in your org. If not, [turn on Data 360](https://help.salesforce.com/s/articleView?id=data.c360_a_setup_provision.htm&type=5&language=en_US).

Prerequisite: Configure Your Client

File uploads are configured separately for the client and for the agent. To receive files, your agent must be connected to clients that are configured to accept file uploads. Otherwise, your end users can't send any files and your agent can't receive them. Requirements vary by client, but these are requirements for common clients.

Enhanced Chat

From the Messaging Settings page in Setup, turn on file sharing for end users. This gives users the ability to attach a file in the chat window. You can also specify allowed file types and maximum file size. See [Customize the File Sharing Experience in Enhanced Chat](https://help.salesforce.com/s/articleView?id=service.enhanced_chat_customer_file_types.htm&type=5&language=en_US).

Make sure that your agent user has required access. If you created an agent user when you created your agent, your agent user is granted the required Messaging Session object permissions and settings by default.

- System Permissions: Chatter Internal User, Access Conversation Entries
- Object Permissions: Messaging Session
- Object Settings: Messaging Session, Messaging User

Experience Cloud

If you’re connecting your agent to an Experience Cloud site that allows guest users, give them permission to upload files. Guest users can upload files to a record only when guest user sharing rules are in place. From Setup, in the Quick Find box, enter Salesforce Files, and select **General Settings**. Then select **Allow site guest users to upload files**.

To configure your agent to accept file uploads, edit your agent's script and give it instructions for how to handle uploaded files.

1. From the Agents list in the Agentforce Studio app, open the agent you want to receive file uploads.
2. Add the [`file_upload` sub-block](https://developer.salesforce.com/docs/ai/agentforce/guide/ascript-blocks.html#file-upload-sub-block) to your agent’s script and specify the mode you want your agent to use for handling file uploads. Use this Agent Script setting to define how your agent uses and stores uploaded files. You can also use this setting to turn off file uploads for your agent.
    1. If you’re viewing the agent in Canvas view, switch to Script view.
    2. In your agent's `config` block, add the `file_upload` field and specify a `mode` value. If you don’t specify a mode and your agent can receive file uploads, `error` mode applies by default.
        
        ```
        config:
            file_upload:
                mode: "auto" | "managed" | "disabled" | "error"
                    
        ```
        
        Available modes:
        
        - `auto`—Files are processed and available in the conversation history. Use this mode to allow the agent to automatically manage how and when files are used. Files are always sent to the LLM.
        - `managed`—Files are stored in the [uploaded\_files system variable (@system\_variables.uploaded\_files)](https://developer.salesforce.com/docs/ai/agentforce/guide/ascript-ref-variables-system.html#uploaded_files), and you use the variable to control how files are used. Files aren’t added to the conversation history. Use this mode to explicitly manage how files are sent to the LLM, which subagents can access the files, and how the files are sent and used by other actions. To give the agent access to uploaded files, directly reference the variable in subagent instructions or assign it to action inputs and outputs. Files are sent to the LLM only when the `uploaded_files` system variable is referenced in subagent instructions.
        - `disabled`—File uploads are turned off silently. Files are received and stored, but they aren't used in the agent conversation or sent to the LLM. See [Turn Off File Uploads for an Agent](https://help.salesforce.com/s/articleView?id=ai.agent_file_upload_disable.htm&release=264.0.0&type=5 "If you no longer want your agent to be able to receive files, turn off file upload capabilities at the agent level.").
        - `error`—File uploads are turned off, and the agent sends an error message. You can customize the error message. Files are received and stored, but they aren't used in the agent conversation or sent to the LLM. If you don’t specify a mode and your agent can receive file uploads, this mode applies by default. See [Turn Off File Uploads for an Agent](https://help.salesforce.com/s/articleView?id=ai.agent_file_upload_disable.htm&release=264.0.0&type=5 "If you no longer want your agent to be able to receive files, turn off file upload capabilities at the agent level.").
3. Customize your subagents and actions.
    1. Give your agent file-handling instructions. For best results, we recommend creating a dedicated subagent for handling file uploads, so you can provide detailed instructions and control subagent routing for your business case. For example, you may want to provide unique instructions for how to handle PDF files versus image files.
        
        ![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-ai-generative_ai-264-0-0-production-enus/f8ef6498-d7b2-44e3-9b34-ffd5a850aae9/images/icon_note.png)
        
        Note Without explicit instructions that your agent can accept file uploads, when your agent receives a file, your agent can redirect the conversation to the Off Topic system subagent. At minimum, in a subagent that you want to use for file handling, tell your agent to use the subagent to process files.
        
        Here’s an example of Agent Script for a File and Image Analysis subagent block.
        
        ```
        subagent File_and_Image_Analysis:
           label: "File and Image Analysis"
           description: |
               Use this topic when the user uploads a PDF, document, or image file and asks to summarize, analyze, describe, extract text from, or answer questions about its contents.
           reasoning:
               instructions: ->
                   | 1. Evaluate standard user requests involving uploaded attachments (PDFs, images, or documents).
                   | 2. When a user asks to describe, summarize, or extract text from an uploaded PDF or image:
                   |    - Identify the primary topics, main takeaways, key data points, and structural highlights from the document or visual content.
                   |    - Provide a clear, structured summary using bullet points or concise paragraphs.
                   |    - Do not guess or fabricate information not present in the attached file.
                   | 3. If the document content is unclear or incomplete, politely ask the user for clarification while describing what is currently visible.
        ```
    2. If you use `managed` mode, make sure the `uploaded_files` system variable is added to your agent. To give your agent access to uploaded files, reference the variable in agent instructions, assign it to agent action inputs or outputs, or both.
        
        To learn more about using the `uploaded_files` system variable, see [_Agentforce Developer Guide_: System Variables](https://developer.salesforce.com/docs/ai/agentforce/guide/ascript-ref-variables-system.html#uploaded_files). To learn more about working with list variables, see [_Agentforce Developer Guide_: Using List Variables](https://developer.salesforce.com/docs/ai/agentforce/guide/ascript-patterns-var-list.html).
4. Save your changes.
5. Before you deploy your agent, test your agent’s file upload configuration. Start a preview conversation in Agentforce Builder and send a file. File uploads can be tested end to end.

Where uploaded files are stored depends on where the file is uploaded. If you upload a file as part of a preview conversation in Agentforce Builder, the file is stored in Data 360. If you upload a file from an external client (for example, Enhanced Chat v2 or SMS), the file is stored in Salesforce Files.

- **[Turn Off File Uploads for an Agent](https://help.salesforce.com/s/articleView?id=ai.agent_file_upload_disable.htm&release=264.0.0&type=5)**  
    If you no longer want your agent to be able to receive files, turn off file upload capabilities at the agent level.
- **[Example: View Uploaded Files in Agentforce Session Tracing](https://help.salesforce.com/s/articleView?id=ai.agent_file_upload_stdm.htm&release=264.0.0&type=5)**  
    Use this example script to connect the assets uploaded during an agent conversation with the session in Agentforce Session Tracing (STDM).