# Analyze Files

> Add the Analyze Files tool to an Agents project to process and reason over file content using LLMs.

The **Analyze Files** tool allows agents to process and reason over file content using LLMs.

## Add the Analyze Files tool

To add the **Analyze Files** tool to your agent, take the following steps:

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

   ![Creating file input arguments in the Data Manager panel](https://dev-assets.cms.uipath.com/assets/images/agents/agents-docs-image-594758-8980271d.webp)

   Input argument must be explicitly referenced in the [user prompt](https://docs.uipath.com/agents/automation-suite/2.2510/user-guide/agent-prompts#user-prompts%E2%80%8B) using the `{{exampleInput}}` syntax. Input arguments that are not referenced are ignored and may affect the [agent's score](https://docs.uipath.com/agents/automation-suite/2.2510/user-guide/agent-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:

   ```text
   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.

   ![Example of an agent with file inputs referenced in the prompt](https://dev-assets.cms.uipath.com/assets/images/agents/input-prompt-example-4dca1ada.png)

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.

   ![Analyze files](https://dev-assets.cms.uipath.com/assets/images/agents/analyzefiles-0ed4c735.webp)

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.

   ![Debugging with multiple files](https://dev-assets.cms.uipath.com/assets/images/agents/debug-with-files-abe2b98a.png)
5. After running the agent, inspect the execution trace via the bottom panel.

The **Analyze Files** tool is now added to your agent and configured to process file inputs. The execution trace in the **Execution Trail** panel shows how each attachment was handled during the run.

## File attachment traces

When using the **Analyze Files** tool, all file inputs and outputs are captured in the **Execution Trail** panel, in the **History** tab. The trace provides detailed visibility into how attachments were handled during agent execution.

For each file, the trace shows:

* **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

   ![The file analysis shown in the Execution Trail panel](https://dev-assets.cms.uipath.com/assets/images/agents/execution-trace-2bc8bec0.webp)

Select the tool call from the execution trace and navigate to the **Files** tab to download the file.

   Figure 3. How to download a file from traces

   ![Downloading a file from the Files tab of a tool call trace](https://dev-assets.cms.uipath.com/assets/images/agents/download-file-7a847ecb.webp)

## Best practices and FAQ

:::note
Refer to [Working with files](https://docs.uipath.com/agents/automation-suite/2.2510/user-guide/working-with-files) for more details on using files from Maestro processes, RPA workflows, or standalone agent runs.
:::

The **Analyze Files** tool enables agents to process documents and images using LLMs. While powerful, there are some important limitations and behaviors to be aware of when designing file-driven agents.

### File limits

Each file must not exceed 30 MB. There is no enforced limit on the number of files per request.

### Supported file types

The **Analyze Files** tool supports the following file types: `.pdf`, `.gif`, `.jpg`, `.jpeg`, `.png`, `.tiff`, `.webp`.

Support for different formats may vary depending on the selected LLM provider and model. Results may also vary between providers and models, especially for files that contain charts, embedded images, or complex layouts.

### File support for custom LLM configurations

The supported file types are the same when you use the Bring Your Own LLM capability through AI Trust Layer. Configuring a provider, model family, or API Type whose underlying model accepts other formats does not extend the file types that the **Analyze Files** tool accepts. For details on configuring a custom LLM, refer to [Configuring LLMs](https://docs.uipath.com/automation-suite/automation-suite/2.2510/admin-guide/configuring-llms).

### How file processing works

When a file is passed to an LLM, the model does not receive the original file as-is. Most providers apply a preprocessing step before the content is added to the model context. The preprocessing behavior depends on the file type.

PDF files can be processed as both extracted text and page images on vision-capable models. Image files are passed to the model as images, subject to the resizing behavior described in [LLMs resize images](#llms-resize-images).

Providers such as OpenAI, AWS Bedrock, and Vertex AI may use different preprocessing approaches, and the exact implementation details are provider-specific and may not be fully documented.

### Large files may exceed token limits

Agents process files by embedding their contents into LLM prompts, which are constrained by the model's token limit. Large PDFs or scanned image documents may silently fail or return vague errors like "An error occurred", especially when they exceed the model's token budget.

To mitigate:
* 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

Large PDFs can exceed the LLM's token budget when processed in full. Split the PDF into smaller chunks or individual pages before passing them to the agent.

### LLMs resize images

When image files (for example, `.jpg`, `.png`) are sent as part of the LLM prompt, most models automatically resize them. This can distort aspect ratios or lose pixel-precise data.

Avoid prompts that rely on exact coordinates, bounding boxes, or pixel-aligned comparisons (for example, image diffs requiring specific x/y positioning). For more information, refer to [OpenAI's image vision guide](https://platform.openai.com/docs/guides/images-vision?api-mode=responses) for model-specific resizing behavior.

### 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.