分析文件

分析文件

分析文件工具使智能体可以使用 LLM 处理文件内容并对其进行推理。

要将分析文件工具添加到您的智能体中，请执行以下步骤：

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

   图 1. 创建文件输入参数

   

   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:

   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. 将分析文件工具添加到智能体定义中：

   1. 在“工具”面板中选择“添加工具”。
   2. 从“内置工具”类别中，选择“分析文件”。
   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. 使用输入文件运行智能体。

   1. 打开“调试配置”窗口：
      1. 导航到“项目参数”选项卡。
      2. 上传绑定到您的 reportFiles 参数的输入文件。
   2. 选择“保存”，然后运行调试会话。

   

5. 运行智能体后，通过底部面板查看执行追踪记录。

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.

文件附件追踪记录

使用分析文件工具时，所有文件输入和输出都捕获到“执行追踪”面板的“历史记录”选项卡中。追踪记录详细显示了智能体执行期间如何处理附件。

对于每个文件，追踪记录显示：

• ID：附件的唯一标识符。

• 名称：原始文件名称（例如 1.jpg）。

• MIME 类型：检测到的文件类型（例如 image/jpeg）。

  图 2. 执行追踪中的文件分析

  

从执行追踪记录中选择工具调用，然后导航到“文件”选项卡以下载文件。

图 3. 如何从追踪记录中下载文件

最佳实践和常见问题解答

备注：

有关使用 Maestro 流程、RPA 工作流或独立智能体运行中的文件的更多详细信息，请参阅“处理文件”。

通过分析文件工具，智能体可以使用 LLM 流程处理文档和图像。虽然功能强大，但在设计文件驱动的智能体时，需要注意一些重要的限制和行为。

大型文件可能超过令牌上限

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.

要减轻：

• 使用令牌容量较高的模型。
• 使用上下文基础，而非完整文件嵌入，尤其适用于大型文件或多页面文件。
• 通过自定义工具，在智能体运行之前或期间对文档进行预索引，并对其进行同步。

LLM 调整图像大小

当图像文件（例如 .jpg、.png）作为 LLM 提示词的一部分发送时，大多数模型会自动调整它们的大小。这可能会导致纵横比失真或像素精确数据丢失。

避免依赖确切坐标、边界框或像素对齐比较的提示词（例如，需要特定 x/y 定位的图像差异）。有关更多信息，请参阅 OpenAI 的图像视觉指南，以了解模型专属的大小调整行为。

支持的文件类型

支持以下文件扩展名：GIF、JPE、JPEG、PDF、PNG、WEBP。

文件类型支持因 LLM 提供程序而异。例如，根据文件名称或编码，某些 Anthropic 模型可能无法提供 PDF 支持。

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.

File limits

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

获得更好结果的提示

• 文件名称必须整洁：特别是 Anthropic 模型会拒绝包含特殊字符或重复空格的文件名称。
• 保持图像数量少：GPT-4o 等某些模型每个请求最多支持 10–50 个图像。