Agents user guide

Analyze Files

link

1. Define file inputs. In the Data Manager panel, add an argument for each file input in your agent schema.

   Figure 1. Creating file input arguments

   

   Input argument must be explicitly referenced in the user prompt using the {{exampleInput}} syntax. Input arguments that are not referenced are ignored and may affect the agent’s score.

   • For a single file, set the argument type to File and reference it in the user prompt. For example: "Analyze the following report and summarize the key findings: {{reportFile}}".
   • To pass multiple files, set the argument type to Array and the item type to File, then reference the argument by name in the user prompt. You can also add optional string arguments for runtime instructions. For example:
   assignment

   Analyze the following report files and summarize the key findings.
   
   ## Inputs
   - Report files: {{reportFiles}}
   - Additional instructions (optional): {{analysisInstructions}}
   Analyze the following report files and summarize the key findings.
   
   ## Inputs
   - Report files: {{reportFiles}}
   - Additional instructions (optional): {{analysisInstructions}}
   

   In this example, reportFiles is an Array of File argument and analysisInstructions is an optional String argument. Both must be defined in the Data Manager panel.

   

   

2. Add the Analyze Files tool to your agent definition:

   1. Select Add tool in the Tools panel.
   2. From the Built-in tools category, choose Analyze Files.
   3. Update the tool name and description to help the agent reason better about when to use it. The name and description guide the agent's planning phase — they determine when the agent decides to call the tool, not what the tool does with the files at runtime.

   

3. Set the tool’s inputs. The tool comes preconfigured with two main inputs:

   • attachments (array): A prompt-defined input that tells the agent which files to pass to the tool. In this field, describe how the agent should use the file inputs referenced in the user prompt (for example, {{reportFiles}}). The agent automatically maps those referenced files to this input at runtime. Example: "Use the files provided in the user prompt (for example, {{reportFiles}}) as inputs for analysis."
   • analysisTask (string): A runtime instruction telling the LLM what to do with the files once the tool is invoked — for example, "Analyze these reports. Extract the report title, an executive summary, key findings ordered by importance, actionable recommendations, and the overall sentiment." This is distinct from the tool name and description, which control when the agent calls the tool. If your use case involves only one file, you can describe attachments accordingly (for example, "Use the file provided in {{reportFile}}…").

4. Run the agent with input files.

   1. Open the Debug configuration window:
      1. Navigate to the Project arguments tab.
      2. Upload your input files bound to your reportFiles argument.
   2. Select Save and run the debug session.

   

5. After running the agent, inspect the execution trace via the bottom panel.

• ID: A unique identifier for the attachment.

• Name: Original file name (for example, 1.jpg).

• MIME type: Detected file type (for example, image/jpeg).

  Figure 2. The file analysis in the execution trail

  

File limits​

File type support by provider​

File support for custom LLM configurations​

• The selected provider, such as Azure OpenAI, Amazon Web Services, or Google Vertex
• The selected model family and model version
• The configured API Type, such as the provider endpoint used to call the model
• The file processing capabilities exposed by that provider endpoint

How file processing works​

• PDF files can be processed as both extracted text and page images on vision-capable models.
• Non-PDF document and text files are processed as extracted text only.
• Spreadsheet files use a spreadsheet-specific augmentation flow. OpenAI parses up to the first 1,000 rows per sheet and adds summary and header metadata so the model can work from a structured representation of the data.

Large files may exceed token limits​

• Use models with higher token capacity.
• Use retrieval-oriented capabilities such as File Search or Context Grounding, especially for large or multi-page files.
• Pre-index documents and sync them before or during the agent run via custom tools.

Handling large PDFs​

LLMs resize images​

Tips for better results​

• File names must be clean: Anthropic models, in particular, reject file names with special characters or repeated whitespace.
• Keep image count low: Some models like GPT-4o support a maximum of 10–50 images per request.
• Use PDF format when layout, charts, or diagrams are important. Embedded images and charts in non-PDF formats such as .docx may not be extracted into the model context.
• Use text-based formats such as .txt, .md, or .html for straightforward document understanding tasks.
• For complex spreadsheet analysis involving aggregations, joins, formulas, or charting, use a deterministic processing step or a dedicated data-processing workflow before passing the result to the agent.