ファイルを分析

ファイルを分析

Analyze Files ツールを使用すると、エージェントは LLM を使用してファイルの内容を処理し、推論を行うことができます。

Analyze Files ツールをエージェントに追加するには、次の手順を実行します。

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. Analyze Files ツールをエージェント定義に追加します。

   1. [ツール] パネルで [ツールを追加] を選択します。
   2. [組み込みツール] カテゴリから [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. 入力ファイルを使用してエージェントを実行します。

   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.

添付ファイルのトレース

Analyze Files ツールを使用すると、すべてのファイルの入力と出力が [実行証跡] パネルの [履歴] タブにキャプチャされます。このトレースにより、エージェントの実行中に添付ファイルがどのように処理されたかを詳細に可視化できます。

ファイルごとに、トレースには以下が表示されます。

• ID: 添付ファイルの一意の識別子です。

• 名前: 元のファイル名です (例: 1.jpg)。

• MIME タイプ: 検出されたファイルの種類です ( image/jpegなど)。

  図 2. [実行証跡] でのファイルの分析

  

実行トレースから [ツールの呼び出し] を選択し、[ファイル] タブに移動してファイルをダウンロードします。

図 3.トレースからファイルをダウンロードする方法

ベスト プラクティスとよくある質問

注:

Maestro プロセス、RPA ワークフロー、またはスタンドアロンのエージェントの実行からのファイルの使用について詳しくは、「ファイルを操作する」をご覧ください。

Analyze Files ツールを使用すると、エージェントは 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 などの一部のモデルでは、1 回の要求で最大 10 〜 50 の画像がサポートされています。