Analyze Files

Analyze Files

Mit dem Tool „Dateien analysieren“ können Agents Dateiinhalte mithilfe von LLMs verarbeiten und analysieren.

Um Ihrem Agent das Tool „Dateien analysieren“ hinzuzufügen, führen Sie die folgenden Schritte aus:

1. Define file inputs. In the Data Manager panel, add an argument for each file input in your agent schema.

   Abbildung 1. Erstellen von Dateieingabeargumenten

   

   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}}".
   • Um mehrere Dateien zu übergeben, legen Sie den Argumenttyp auf Array und den Elementtyp auf Datei fest und verweisen Sie dann auf das Argument anhand des Namens im Benutzerprompt. Sie können auch optionale String-Argumente für Runtime-Anweisungen hinzufügen. Zum Beispiel:

   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. Fügen Sie Ihrer Agent-Definition das Tool „Dateien analysieren“ hinzu:

   1. Wählen Sie im Bereich Tools die Option Tool hinzufügen aus.
   2. Wählen Sie in der Kategorie „Integrierte Tools“ die Option „Dateien analysieren“ aus.
   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 (Zeichenfolge): Eine Runtime-Anweisung, die dem LLM mitteilt, was mit den Dateien geschehen soll, wenn das Tool aufgerufen wird – z. B. „Analysieren Sie diese Berichte. Extrahieren Sie den Berichtstitel, eine Zusammenfassung, wichtige Ergebnisse nach Wichtigkeit geordnete Empfehlungen und die allgemeine Stimmung. Diese unterscheidet sich vom Toolnamen und der Beschreibung, die steuern, wann der Agent das Tool aufruft. Wenn Ihr Anwendungsfall nur eine Datei umfasst, können Sie Anhänge entsprechend beschreiben (z. B. „Verwenden Sie die in {{reportFile}}bereitgestellte Datei …“).

4. Führen Sie den Agent mit Eingabedateien aus.

   1. Öffnen Sie das Fenster Debug-Konfiguration :
      1. Navigieren Sie zur Registerkarte Projektargumente .
      2. Laden Sie Ihre Eingabedateien hoch, die an Ihr Argument gebunden sindreportFiles.
   2. Wählen Sie Speichern aus und führen Sie die Debug-Sitzung aus.

   

5. Überprüfen Sie nach der Ausführung des Agents die Ausführungsablaufverfolgung über den unteren Bereich.

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.

Ablaufverfolgungen von Dateianhängen

Bei Verwendung des Tools „Dateien analysieren“ werden alle Dateieingaben und Ausgaben im Bereich „Ausführungspfad“ auf der Registerkarte „Verlauf“ erfasst. Die Ablaufverfolgung bietet einen detaillierten Überblick darüber, wie Anhänge während der Ausführung des Agents verarbeitet wurden.

Für jede Datei zeigt die Ablaufverfolgung Folgendes an:

• ID: Ein eindeutiger Bezeichner für den Anhang.

• Name: Ursprünglicher Dateiname (z. B. 1.jpg).

• MIME-Typ: Erkannter Dateityp (z. B. image/jpeg).

  Abbildung 2. Die Dateianalyse im Ausführungspfad

  

Wählen Sie den Toolaufruf aus der Ausführungsablaufverfolgung aus und navigieren Sie zur Registerkarte Trace, um die Datei herunterzuladen.

Abbildung 3. So laden Sie eine Datei aus Ablaufverfolgungen herunter.

Bewährte Methoden und FAQ

Hinweis:

Weitere Details zur Verwendung von Dateien aus Maestro-Prozessen, RPA-Workflows, eigenständigen Agent-Ausführungen oder Processes finden Sie unter Arbeiten mit Dateien.

Mit dem Tool „Dateien analysieren“ können Agents Dokumente und Bilder mit LLMs im Prozess verarbeiten.Trotz ihrer Leistungsfähigkeit gibt es einige wichtige Einschränkungen und Verhaltensweisen, die beim Entwerfen von dateigesteuerten Agents berücksichtigt werden müssen.

Große Dateien können die Tokenlimits überschreiten

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.

Zur Minderung:

• Verwenden Sie Modelle mit höherer Tokenkapazität.
• Verwenden Sie die Kontextgrundlage anstelle der vollständigen Dateieinbettung, insbesondere für große oder mehrseitige Dateien.
• Sie können Dokumente vorindizieren und sie vor oder während der Ausführung des Agents über benutzerdefinierte Tools synchronisieren.

LLMs ändern die Größe von Bildern

Wenn Bilddateien (z. B. .jpg, .png) als Teil des LLM-Prompt gesendet werden, ändern die meisten Modelle automatisch ihre Größe. Dadurch können Seitenverhältnisse verzerrt oder pixelgenaue Daten verloren gehen.

Vermeiden Sie Prompts, die auf exakten Koordinaten, Begrenzungsfeldern oder pixelausgerichteten Vergleichen basieren (z. B. Bildunterschiede, die eine bestimmte x/y-Positionierung erfordern). Weitere Informationen zum modellspezifischen Verhalten bei der Größenänderung finden Sie im Leitfaden zur Bildverarbeitung und -analyse von OpenAI.

Unterstützte Dateitypen

Folgende Dateierweiterungen werden unterstützt: GIF, JPE, JPEG, PDF, PNG, WEBP.

Die Unterstützung des Dateityps variiert je nach LLM-Anbieter. Zum Beispiel kann die PDF-Unterstützung bei einigen Anthropic-Modellen je nach Dateiname oder Codierung fehlschlagen.

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.

Tipps für bessere Ergebnisse

• Dateinamen müssen fehlerfrei sein: Insbesondere anthropische Modelle lehnen Dateinamen mit Sonderzeichen oder wiederholten Leerzeichen ab.
• Halten Sie die Anzahl der Bilder niedrig: Einige Modelle wie GPT-4o unterstützen maximal 10 bis 50 Bilder pro Anforderung.