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

  

Best practices and FAQ​

• Use models with higher token capacity.
• Use Context Grounding instead of full file embedding, especially for large or multi-page files.
• Pre-index documents and sync them before or during the agent run via custom tools.

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