ファイルを分析

ファイルを分析

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

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

1. ファイル入力を定義します。[ データ マネージャー ] パネルで、エージェント スキーマの各ファイル入力に対して引数を追加します。

   図 1. ファイル入力引数の作成

   

   入力引数は、{{exampleInput}} 構文を使用してユーザー プロンプトで明示的に参照する必要があります。参照されていない入力引数は無視され、 エージェントのスコアに影響を与える可能性があります。

   • ファイルが 1 つの場合は、引数の型を File に設定し、ユーザー プロンプトで参照します。たとえば、「次のレポートを分析し、主な調査結果を要約してください。 {{reportFile}}」と表示されます。
   • 複数のファイルを渡すには、引数の型を Array に、項目の型を File に設定してから、ユーザー プロンプトで引数を名前で参照します。また、実行時の指示用に任意の文字列引数を追加することもできます。例えば：

   Analyze the following report files and summarize the key findings.
   
   ## Inputs
   - Report files: {{reportFiles}}
   - Additional instructions (optional): {{analysisInstructions}}
   

   この例では、 reportFiles は File 引数の配列 で、 analysisInstructions はオプションの String 引数です。どちらも [ データ マネージャー ] パネルで定義する必要があります。

   

   

2. Analyze Files ツールをエージェント定義に追加します。

   1. [ツール] パネルで [ツールを追加] を選択します。
   2. [組み込みツール] カテゴリから [Analyze Files] を選択します。
   3. ツールの名前と説明を更新して、エージェントがツールをいつ使用すべきかをより適切に判断できるようにします。名前と説明は、エージェントの計画フェーズの指針となります。名前と説明は、エージェントがツールを呼び出すタイミングを決定するものであり、実行時にツールがファイルに対して行う処理ではありません。

   

3. ツールの入力を設定します。このツールは、次の 2 つの主要な入力で事前設定されています。

   • attachments (配列): ツールに渡すファイルをエージェントに指示する、プロンプトで定義された入力です。このフィールドには、ユーザー プロンプトで参照されるファイル入力 ( {{reportFiles}}など) をエージェントがどのように使用するかを記述します。エージェントは、実行時にこれらの参照ファイルをこの入力に自動的にマッピングします。例: 「ユーザー プロンプトで提供されたファイル (例: {{reportFiles}}) を分析の入力として使用してください。」
   • analysisTask (文字列): ツールが呼び出された後にファイルを処理する方法を LLM に指示する実行時の指示 (例: 「これらのレポートを分析してください。レポートのタイトル、エグゼクティブサマリー、重要な調査結果を重要度順に並べ、実用的な推奨事項、全体的な感情を抽出します。これは、エージェントがツールを呼び出すタイミングを制御するツールの名前と説明とは異なります。ユース ケースに含まれるファイルが 1 つのみの場合は、添付ファイルを適宜記述できます (例: 「Use the file provided in {{reportFile}}...").

4. 入力ファイルを使用してエージェントを実行します。

   1. 次の手順を実行して [デバッグ設定] ウィンドウを開きます。
      1. [プロジェクトの引数] タブに移動します。
      2. reportFiles 引数にバインドされている入力ファイルをアップロードします。
   2. [保存] を選択してデバッグ セッションを実行します。

   

5. エージェントの実行後、下部のパネルで実行トレースを確認します。

これで、 ファイルの分析 ツールがエージェントに追加され、ファイル入力を処理するように設定されました。[実行証跡] パネルの実行トレースには、実行中に各添付ファイルがどのように処理されたかが示されます。

添付ファイルのトレース

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

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

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

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

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

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

  

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

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

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

注:

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

Analyze Files ツールを使用すると、エージェントは LLM を使用してドキュメントや画像を処理できます。これは強力な機能ですが、ファイル駆動型エージェントを設計する際に注意すべき重要な制限事項と動作がいくつかあります。

大きなファイルはトークンの制限を超過する可能性がある

エージェントは、その内容を LLM プロンプトに埋め込むことでファイルを処理します。LLM プロンプトは、モデルのトークン制限によって制約されます。大きな PDF やスキャンされた画像ドキュメントは、特にモデルのトークンのバジェットを超えた場合に、警告なしに失敗したり、「エラーが発生しました」などのあいまいなエラーが返されたりすることがあります。

この問題を軽減するには、以下の手順に従います。

• トークン容量の大きいモデルを使用します。
• 特に、大きなファイルや複数ページのファイルの場合は、ファイル全体の埋め込みではなくコンテキスト グラウンディングを使用します。
• ドキュメントを事前にインデックス化し、カスタム ツールを使用してエージェントの実行前または実行中に同期します。

LLM により画像のサイズが変更される

画像ファイル (.jpg、 .png など) を LLM プロンプトの一部として送信すると、ほとんどのモデルで自動的にサイズが変更されます。これにより、アスペクト比が歪んだり、ピクセル単位のデータが失われたりする可能性があります。

正確な座標、境界ボックス、またはピクセル整列された比較に依存するプロンプト (特定の X/Y 位置を必要とする画像の差分など) は避けてください。モデル固有のサイズ変更動作の詳細については、OpenAI の画像ビジョン ガイドをご覧ください。

サポートされているファイルの種類

サポートされているファイル拡張子は、GIF、JPE、JPEG、PDF、PNG、WEBP です。

ファイルの種類のサポートは、LLM プロバイダーによって異なります。たとえば、ファイル名やエンコードによっては、一部の Anthropic モデルで PDF が正しくサポートされない場合があります。

サイズの大きい PDF を処理する

サイズの大きな PDF を完全に処理すると、LLM のトークンのバジェットを超える可能性があります。PDF を小さなチャンクまたは個々のページに分割してから、エージェントに渡します。

ファイルの制限

各ファイルは 30 MB を超えてはなりません。要求あたりのファイル数に制限はありません。

より良い結果を得るためのヒント

• ファイル名はクリーンである必要があります。特に Anthropic モデルでは、特殊文字や空白の繰り返しが含まれるファイル名は拒否されます。
• 画像数を少なくします。GPT-4o などの一部のモデルでは、1 回の要求で最大 10 〜 50 の画像がサポートされています。