unzip_object – ZIP-Dateien entpacken (ALBERT | AI Tool)

Anzeigename: Unzips a ZIP file in agorum core

Technischer Name: agorum_ai_agents_library_basic_unzip_object

Hinweise:

Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins ALBERT | AI Agents. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.
Wie Sie die KI-Tools in Ihren KI-Voreinstellungen verwenden, erfahren Sie hier: ALBERT | AI agents tools einrichten
Das Tool steht einzeln und in der Toolgruppe zip_tools_group zur Verfügung.

Was macht das Tool?

Das Tool unzip_object entpackt eine ZIP-Datei, die in agorum core gespeichert ist, mit allen Dateien und Ordnern. Die Ordnerstruktur der ZIP-Datei bleibt dabei erhalten.

Der Inhalt landet immer in einem neuen Ordner:

Ist ein Zielordner angegeben, wird der neue Ordner unterhalb des Zielordners angelegt.
Ist kein Zielordner angegeben, wird der neue Ordner temporär angelegt.

Der neue Ordner trägt den Namen der ZIP-Datei ohne Endung oder den Namen aus dem Parameter folderName. Ist dieser Name im Zielordner bereits vergeben, wird ein Zähler angehängt, z. B. rechnungen (1). So vermischen sich mehrere Entpackvorgänge nicht.

Das Tool gibt die UUID des neuen Ordners sowie eine Liste der entpackten Dateien zurück. Die KI kann damit direkt mit den entpackten Dateien weiterarbeiten, ohne den Ordner erst durchsuchen zu müssen.

Empfohlener Einsatzzweck

Verwenden Sie unzip_object, um:

eine ZIP-Datei aus einer E-Mail oder einem Upload zu entpacken und die enthaltenen Dokumente anschließend durch die KI auswerten, umbenennen oder ablegen zu lassen
ZIP-Archive mit Ordnerstruktur in agorum core zu übernehmen
den Inhalt einer ZIP-Datei temporär bereitzustellen, etwa um ihn zusammenzufassen, ohne ihn dauerhaft abzulegen

Funktionsbeschreibung

Die folgende Tabelle beschreibt die Parameter des Tools. Parameter, die mit (nur Konfiguration) gekennzeichnet sind, werden in der Tool-Konfiguration durch den Administrator festgelegt und sind für die KI nicht sichtbar.

Parameter	Beschreibung
id (Pflicht)	Die ZIP-Datei in agorum core, die entpackt werden soll. Angabe als ID, UUID oder Pfad.
targetId (Optional)	Ordner, unterhalb dessen der neue Ordner mit dem entpackten Inhalt angelegt wird. Angabe als ID, UUID oder Pfad. Standard: – (die ZIP-Datei wird temporär entpackt)
folderName (Optional)	Name des neuen Ordners, in den entpackt wird. Standard: Name der ZIP-Datei ohne Endung
allowedBasePathIds (Optional, nur Konfiguration)	Liste von Basispfaden (ID, UUID oder Pfad). Der Zielordner `targetId` muss unterhalb eines dieser Pfade liegen, sonst meldet das Tool einen Fehler und legt nichts an. Standard: – (keine Einschränkung)
maxEntries (Optional, nur Konfiguration)	Höchstzahl der Einträge (Dateien und Ordner), die eine ZIP-Datei enthalten darf. Standard: `5000`
maxTotalSize (Optional, nur Konfiguration)	Höchstsumme des entpackten Inhalts in Bytes. Gezählt werden die tatsächlich geschriebenen Bytes, nicht die Größenangaben, die die ZIP-Datei über sich selbst macht. Standard: `1073741824` (1 GB)

Rückgabe

Das Tool gibt ein JSON-Objekt mit folgenden Angaben zurück:

Feld	Beschreibung
uuid, name, objectLink	UUID, Name und Objektlink des neuen Ordners mit dem entpackten Inhalt
temporary	`true`, wenn temporär entpackt wurde
fileCount	Anzahl der entpackten Dateien
folderCount	Anzahl der Ordner, die unterhalb des neuen Ordners angelegt wurden
files	Liste der entpackten Dateien mit UUID, Name und Pfad relativ zum neuen Ordner. Die Liste enthält höchstens 100 Dateien.
filesTruncated	`true`, wenn die ZIP-Datei mehr als 100 Dateien enthielt und `files` deshalb nur die ersten 100 aufführt

Verhalten im Detail

Umlaute in Dateinamen: Einträge, die in der ZIP-Datei als UTF-8 gekennzeichnet sind, werden als UTF-8 gelesen, alle anderen im Zeichensatz Cp850, den der Windows-Explorer verwendet. Umlaute werden deshalb auch bei ZIP-Dateien aus dem Windows-Explorer richtig gelesen.
Sichere Pfade: Pfadangaben wie .. oder ein führender Schrägstrich werden verworfen. Kein Eintrag kann außerhalb des neuen Ordners landen.
Dateinamen: Zeichen, die unter Windows in Dateinamen nicht erlaubt sind, werden durch _ ersetzt.
Verschachtelte ZIP-Dateien werden nicht mit entpackt, sondern als Datei abgelegt. Die KI kann das Tool bei Bedarf erneut auf sie anwenden.
Schutzgrenzen: Überschreitet eine ZIP-Datei maxEntries oder maxTotalSize, bricht das Tool ab, verschiebt den bereits angelegten Ordner in den Papierkorb und meldet, welche Grenze überschritten wurde. So schützen die Grenzen vor übergroßen Archiven. Dasselbe gilt für jeden anderen Fehler beim Entpacken: Ein halb entpackter Ordner bleibt nicht zurück.
Keine ZIP-Datei: Enthält das Objekt keine ZIP-Einträge, weil es leer oder keine ZIP-Datei ist, meldet das Tool einen Fehler.
Gleiche Namen: Gibt es im Ordner bereits eine Datei mit demselben Namen, erhält die entpackte Datei einen Zähler, z. B. bericht (1).pdf.
Der neue Ordner und die entpackten Dateien werden als von der KI erstellt gekennzeichnet.

Beispiel

Beispiel-Prompts:

Entpacke die angehängte ZIP-Datei und liste mir alle enthaltenen PDF-Dateien auf.

Entpacke rechnungen.zip in meinen Ordner Buchhaltung.

Tipps und Tricks

Tipp: Soll die KI Dateien nur in bestimmte Bereiche entpacken dürfen, schränken Sie die möglichen Zielordner über den Parameter allowedBasePathIds ein.

Tipp: Enthält eine ZIP-Datei mehr als 100 Dateien, kann die KI den neuen Ordner über das Tool directory_tree weiter erkunden.

Zum Packen von Dateien und Ordnern siehe zip_objects – Dateien und Ordner als ZIP-Datei packen (ALBERT | AI Tool).