Set Up File Uploads for an Agent

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), 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.
• 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.

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.