- Introduction
- Getting started
- Process modeling with BPMN
- Process modeling with Case Management
- Designing a persistent case entity schema
- Defining case keys (system vs. external)
- Establishing task I/O and write-back contracts
- Exit rules and early stage termination
- Modeling primary and secondary stages
- Triggering a case from Data Fabric
- Implementing stage-level personas and permissions
- Setting SLAs and automated escalation rules
- Configuring a rework loop (re-entry)
- Managing live case instances: pause, migrate, and retry
- Maestro case management component dictionary
- Process modeling with Flow
- Getting started
- Core concepts
- Node reference
- Build guides
- Best practices
- Reference
- Process implementation
- Debugging
- Simulating
- Publishing and upgrading agentic processes
- Common implementation scenarios
- Extracting and validating documents
- Process operations
- Process monitoring
- Process optimization
- Reference information
Maestro user guide
What it does
Analyze Files is a built-in tool you attach to an Autonomous Agent. It passes one or more files to a large language model (LLM) to extract, synthesize, or answer queries about their content.
The files can be documents, images, or other attachments. The agent decides when to call the tool while reasoning, passing in the files and a task, and the tool returns the result for the agent to use.
When to use this
Connect Analyze Files when the agent needs to read mixed file types, or two or more attachments at once, and answer a question or pull content from them.
Reach for Analyze Files over the alternatives in these cases:
- You have one or more files of varied types (documents, images, scans) and want the agent to extract or reason over their content.
- The task is described in natural language ("summarize this document", "what is in this image", "extract the key points") rather than a fixed schema of fields.
For other shapes of work:
- To synthesize across a long document (up to 1,000 pages) with citations, use the Summarize tool.
- To pull structured, typed fields from a document using a trained model, use the Extract node.
Adding the tool to an agent
Analyze Files attaches to an Autonomous Agent as a tool. It does not run on its own.
- Add an Autonomous Agent to the canvas.
- From the node palette, open the Agent tools category and select Analyze Files. Flow adds the tool node to the canvas.
- Connect the tool to the agent's tool handle.
- Select the tool node to open its properties panel.
- Configure the tool as described below.
Result: The Analyze Files tool is connected to the agent. The agent can now call it while reasoning.
Configuration reference
Configure the tool in the Analyze Files Settings section of the properties panel.
| Field | Required | Default | Description |
|---|---|---|---|
| Tool description | No | Analyze one or more files with an LLM to extract, synthesize, or answer queries about their content. | Natural-language description of what the tool does, used by the agent to decide when to call it. Refine it to restrict when the agent uses the tool. |
| attachments (array) | No | Array of files, documents, images, or other attachments to process | Description of the files the agent passes to the tool. Edit it to tell the agent what kind of attachments to send. |
| items (file) | No | Empty | Optional per-item description for a single file within the attachments array. Leave it empty if the array-level description is enough. |
| analysisTask (string) | Yes | None | Task, question, or instruction for processing the files. Describe it in plain language, for example summarize this document, extract key points, or what is in this image. |
| Simulation settings | No | Collapsed | Example calls used to test the tool without invoking the live model. Select Add example call to define an example. |
Inputs and outputs
Inputs
The agent supplies the files and the task when it calls the tool. The configuration above defines what the agent can pass and how the tool behaves.
Output
The tool returns its result to the agent that called it. When you need to read the tool's output directly in the flow, access it at $vars.<nodeName>.output, where <nodeName> is the name of the Analyze Files node on the canvas.
$vars.analyzeFiles1.output
$vars.analyzeFiles1.output
In most flows you don't read the tool output directly. The agent consumes the result as part of its reasoning and returns its own result on $vars.<agentNode>.output. Refer to Agent for the agent's output shape.
Example
An agent processes an incoming email with mixed attachments (a scanned receipt image and a PDF statement) and answers a question about them.
- Add an Autonomous Agent to the canvas.
- From the palette, open Agent tools and select Analyze Files.
- Connect the tool to the agent's tool handle.
- In the Analyze Files tool, edit attachments (array) to describe what the agent should send, for example
The receipt image and statement PDF attached to the incoming email. - Set analysisTask (string) to the work you want done:
Read each attached file. Identify the merchant, the date, and the total amount on
the receipt, and confirm whether the statement lists a matching charge.
Read each attached file. Identify the merchant, the date, and the total amount on
the receipt, and confirm whether the statement lists a matching charge.
- In the agent's user prompt, instruct it to use the tool, for example:
Use the Analyze Files tool to check the attachments and tell me whether the receipt matches a charge on the statement.
When the agent runs, it calls Analyze Files with the attachments, receives the analysis, and returns its response on $vars.agent1.output.content.