ファイルを分析

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

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

Analyze Files ツールを追加する

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 の 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 を超えてはなりません。要求あたりのファイル数に適用される制限はありません。

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

The Analyze Files tool supports the following file types: .pdf, .gif, .jpg, .jpeg, .png, .tiff, .webp.

Support for different formats may vary depending on the selected LLM provider and model. Results may also vary between providers and models, especially for files that contain charts, embedded images, or complex layouts.

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

The supported file types are the same when you use the Bring Your Own LLM capability through AI Trust Layer. Configuring a provider, model family, or API Type whose underlying model accepts other formats does not extend the file types that the Analyze Files tool accepts. For details on configuring a custom LLM, refer to Configuring LLMs.

ファイル処理の仕組み

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

PDF files can be processed as both extracted text and page images on vision-capable models. Image files are passed to the model as images, subject to the resizing behavior described in LLMs resize images.

Providers such as OpenAI, AWS Bedrock, and Vertex AI may use different preprocessing approaches, and the exact implementation details are provider-specific and may not be fully documented.

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

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

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

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

大きな PDF を処理する

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

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

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

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

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

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