Working with files

Agents support working with files as both inputs and outputs. This allows you to pass files from Maestro processes, RPA workflows, or standalone agent runs, and to receive files from tools that generate them.

This section outlines how to configure agents to accept files, which tools support file handling, known limitations, and examples for integrating file inputs across different execution environments.

Preparing an agent to accept files

1. Open the agent definition.
2. In Data manager, create a new input.
3. Change the input type to File using the type selector.

An agent must also include at least one tool capable of processing the file. Agents do not process files directly without a tool. The following tools can accept or produce files:

• RPA workflows – Workflows containing activities that process files.

• IXP – Custom or templated models for extracting fields from structured, semi-structured, or unstructured documents.

• Analyze Files – Sends compatible files directly to the model.

  

The following tools are not yet compatible with file inputs or outputs. File support is expected in upcoming releases.

• API workflows
• MCP servers
• Integration Service activities – As a workaround, you can use RPA workflows to handle file operations.
• Context grounding – Indexes can be referenced, but cannot yet be given files directly for just-in-time search.
• Escalations – To work with files, first upload the file to a storage bucket, then import and display it using the Document Viewer and App File variable.

Passing files from a Maestro process

To pass a file to an agent inside a Maestro process:

1. Ensure the process includes an activity or workflow that outputs a file.
2. Alternatively, add an argument of type file if the process receives a file at the start.

3. Add the agent with a file input and map the file variable to the agent’s input.
4. Run the process in debug or deployed mode; the agent can receive runtime files.

Passing files from an RPA workflow

To pass a file from an RPA workflow:

1. Ensure an activity or trigger in the workflow produces a file.
2. Use the Run Job activity and reference an agent that has a file input.

Note:

Studio Desktop 2025.10.0 or later is required for file support.

Using files in evaluations

When an agent defines an input argument of type file, the evaluation setup allows you to upload or select files that are used as test inputs during evaluation runs. This makes it possible to validate agent behavior against real documents or images, such as screenshots, PDFs, or other supported file types.

To use files in evaluations:

1. Open the agent and navigate to Evaluation Sets.
2. Create a new evaluation or edit an existing one.
3. In the Input setup panel, locate the File input field.
4. Upload a new file or select one from the available evaluation files.
5. Save the evaluation and run the evaluation set.

The selected file is passed to the agent in the same way as a runtime file input, ensuring consistent behavior between evaluations and production runs.

When working with file inputs in evaluations, you can:

• Upload files directly from the evaluation setup flow
• View previously uploaded files
• Select which file to use for a given evaluation input

Files selected during evaluation setup are only used for evaluation runs and do not affect production agent executions.

Note:

Files are currently not supported in simulation mode.