ファイルを分析

Analyze Files ツールを Agents プロジェクトに追加し、LLM を使用してファイルの内容を処理および推論します。

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

Analyze Files ツールを追加する

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

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

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

   • ファイルが 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 の Array 型の引数、analysisInstructions は String 型の引数 (任意) です。両方を [データ マネージャー] パネルで定義する必要があります。

   

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

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

   

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

   • attachments (配列): ツールに渡すファイルをエージェントに指示する、プロンプトで定義された入力です。このフィールドには、ユーザー プロンプトで参照されているファイル入力 ({{reportFiles}} など) をエージェントがどのように使用すべきかの説明を入力します。エージェントは実行時に、参照されているそれらのファイルを、この入力に自動的にマッピングします。例: 「ユーザー プロンプトで指定されているファイル (例: {{reportFiles}}) を分析の入力として使用してください。」
   • analysisTask (文字列): ツールが呼び出された後に、ファイルを処理する方法を LLM に指示する実行時の指示です (例: 「これらのレポートを分析してください。レポートのタイトル、事業計画概要、重要度別の主な知見、実用的な推奨事項、全体的な感情を抽出してください」)。これはツールの名前や説明とは異なります。ツールの名前や説明では、エージェントがツールを呼び出すタイミングを制御します。ユース ケースに含まれるファイルが 1 つだけである場合は、それに応じて添付ファイルを説明できます (例: 「{{reportFile}} で提供されているファイルを使用してください...」)。

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

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

   

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

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

添付ファイルのトレース

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

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

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

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

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

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

  

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

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

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

注:

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

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

ファイルの制限

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

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

Analyze Files ツールでサポートされているファイルの種類は、.pdf、.gif、.jpg、.jpeg、.png、.tiff、.webpです。

異なる形式のサポートは、選択した LLM プロバイダーとモデルによって異なる場合があります。また、プロバイダーやモデルによって結果が異なる場合もあります。特に、グラフ、埋め込み画像、または複雑なレイアウトを含むファイルの場合にはそう言えます。

カスタムの LLM 設定でのファイルのサポート

サポートされるファイルの種類は、AI Trust Layer 経由で [独自の LLM を使用する] 機能を使用する場合も同じです。基になるモデルが他の形式を受け入れるプロバイダー、モデル ファミリ、または API の種類を設定しても、 Analyze Files ツールで指定できるファイルの種類は拡張されません。カスタム LLM の設定について詳しくは、「 LLM を設定する」をご覧ください。

ファイル処理の仕組み

ファイルが LLM に渡される際、モデルが元のファイルをそのまま受け取ることはありません。ほとんどのプロバイダーでは、モデル コンテキストに追加する前にコンテンツの前処理ステップを組み込んでいます。前処理の動作は、ファイルの種類によって異なります。

PDF ファイルは、視覚対応モデルでは、抽出テキストとページ画像の両方として処理できます。画像ファイルは画像としてモデルに渡されます。ただし、「 LLM による画像のサイズ変更」で説明されているサイズ変更動作に従います。

OpenAI、AWS Bedrock、Vertex AI などのプロバイダーでは異なる前処理アプローチが使用されている場合があり、正確な実装の詳細はプロバイダー固有であり、完全に文書化されていない場合があります。

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

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

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

• トークン容量の大きいモデルを使用します。
• サイズの大きいファイルや複数ページのファイルの場合は特に、ファイル検索やコンテキスト グラウンディングなどの検索指向の機能を使用します。
• ドキュメントを事前にインデックス化し、カスタム ツールを使用してエージェントの実行前または実行中に同期します。

大きな PDF を処理する

大きな PDF を完全に処理すると、LLM のトークン予算を超える可能性があります。大きな PDF は、エージェントに渡す前に、小さいチャンクまたは個別のページに分割してください。

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

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

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

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

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