ファイルを分析

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

Add the Analyze Files tool

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

File type support by provider

File support depends on the LLM provider and model selected for the agent. Although multiple providers support formats such as PDF, Word documents, spreadsheets, HTML, text, Markdown, and images, each provider may process these files differently before sending the content to the model. Results may vary between providers and models, especially for files that contain charts, embedded images, complex layouts, formulas, or large tables.

The table below shows the formats supported by the latest models exposed by UiPath:

Provider / model family	Supported document and text formats	Supported image formats
Anthropic models through AWS Bedrock	.pdf, .csv, .doc, .docx, .xls, .xlsx, .html, .txt, .md	.gif, .jpe, .jpeg, .pdf, .png, .tiff, .webp
OpenAI GPT models	.pdf, .csv, .doc, .docx, .xls, .xlsx, .html, .txt, .md	.gif, .jpe, .jpeg, .pdf, .png, .tiff, .webp
Gemini models through Vertex AI	.csv, .txt, .md, .html	.gif, .jpe, .jpeg, .pdf, .png, .tiff, .webp

注:

Support depends on the selected model and provider capabilities. Some models may support a file extension at the API level but process the file differently internally, which can affect the quality of the response.

File support for custom LLM configurations

When using the Bring Your Own LLM capability through AI Trust Layer, the file types supported by Analyze Files depend on the configured LLM setup. For details, refer to Configuring LLMs.

File support is determined by the combination of:

• The selected provider, such as Azure OpenAI, Amazon Web Services, or Google Vertex
• The selected model family and model version
• The configured API Type, such as the provider endpoint used to call the model
• The file processing capabilities exposed by that provider endpoint

A file type that works with one model or provider may not work with another, even when both models are available through AI Trust Layer. For example, support for documents, spreadsheets, images, and PDFs can vary depending on whether the provider API accepts those files directly, extracts text from them, converts them into images, or applies a provider-specific preprocessing step.

UiPath validates that the configured LLM endpoint is reachable and compatible with the selected product configuration. When using a custom LLM configuration, you are responsible for ensuring that the configured model, provider, and API Type support the file types required by your Analyze Files use case.

注:

File compatibility may change when switching from a UiPath-managed model to a custom LLM configuration, or when changing the provider, model version, or API Type. If Analyze Files fails to process a file after changing the LLM configuration, review the configured provider, model, and API Type in AI Trust Layer.

How file processing works

When a file is passed to an LLM, the model does not receive the original file as-is. Most providers apply a preprocessing step before the content is added to the model context. The preprocessing behavior depends on the file type.

For OpenAI file inputs:

• PDF files can be processed as both extracted text and page images on vision-capable models.
• Non-PDF document and text files are processed as extracted text only.
• Spreadsheet files use a spreadsheet-specific augmentation flow. OpenAI parses up to the first 1,000 rows per sheet and adds summary and header metadata so the model can work from a structured representation of the data.

Other providers such as AWS Bedrock and Vertex AI may use similar preprocessing approaches, but the exact implementation details are provider-specific and may not be fully documented.

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

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

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

• トークン容量の大きいモデルを使用します。
• Use retrieval-oriented capabilities such as File Search or Context Grounding, especially for large or multi-page files.
• ドキュメントを事前にインデックス化し、カスタム ツールを使用してエージェントの実行前または実行中に同期します。

大きな 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. Embedded images and charts in non-PDF formats such as .docx may not be extracted into the model context.
• Use text-based formats such as .txt, .md, or .html for straightforward document understanding tasks.
• For complex spreadsheet analysis involving aggregations, joins, formulas, or charting, use a deterministic processing step or a dedicated data-processing workflow before passing the result to the agent.