Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > ALBERT | AI > ALBERT | AI Agents


ALBERT | AI Sandbox

Sie können isolierte Arbeitsumgebungen zur Ausführung von KI-Aufgaben einrichten.

Jede Sandbox wird bei Bedarf über einen REST-Service erstellt, als Docker-Container gestartet und enthält alles, was ein autonomer Agent benötigt:

Wenn menschliche Intervention erforderlich ist, kann derselbe Desktop in jedem modernen Browser geöffnet werden, sodass Anmeldedaten oder Multi-Faktor-Abfragen interaktiv bearbeitet werden können.

Hinweis: Für die Einrichtung von ALBERT | AI Sandbox verwenden Sie folgendes GIT-Projekt:

ALBERT | AI Sandbox 

Hauptfunktionen

Systemanforderungen

Komponente Anforderung
Betriebssystem Debian 12 (bookworm) verifiziert; vergleichbare Debian-basierte Systeme sollten mit äquivalenten Paketen funktionieren
Berechtigungen Root-Zugriff zum Ausführen des Installers, Verwalten von Services und Konfigurieren von nginx
Docker Docker Engine und systemd müssen auf dem Host verfügbar sein
Netzwerk Internetverbindung während der Installation zum Abrufen von Docker-Komponenten und Python-Paketen

Installation

Gehen Sie wie folgt vor, um ALBERT | AI Sandbox zu installieren:

  1. Melden Sie sich auf einem Debian 12 Host mit Root-Rechten an.
  2. Klonen Sie das Repository und führen Sie den Installer aus:
    git clone https://github.com/agorum/albert-ai-sandbox.git albert-ai-sandbox
    cd albert-ai-sandbox
    sudo bash install.sh
    
  3. Der Installer stellt alle erforderlichen Pakete bereit, erstellt das Desktop-Container-Image, registriert den Manager-Service und platziert Hilfsskripte unter /opt/albert-ai-sandbox-manager mit praktischen Symlinks in /usr/local/bin.
  4. Nach der Installation läuft der albert-container-manager systemd-Service auf Port 5001 und ist bereit, API-Aufrufe zu empfangen.

Achtung: Für den Betrieb sind Docker und systemd zwingend erforderlich. Die Installation muss mit Root-Rechten erfolgen.

API-Key-Verwaltung

Damit agorum core mit dem ALBERT | AI Sandbox Server kommunizieren kann, muss ein API-Schlüssel erstellt werden. Jeder API-Schlüssel ist einem Benutzer oder einer Anwendung zugeordnet und ermöglicht die Verwaltung eigener Sandboxes.

API-Key erstellen

Führen Sie auf dem Sandbox-Server folgenden Befehl aus:

sudo /opt/albert-ai-sandbox-manager/scripts/api-key-manager.sh create --label "agorum core Integration"

Der Befehl gibt einen API-Schlüssel zurück, der wie folgt aussieht:

OPpDNFekdM5hUuQsboNhgTfUB0nuKYXyE_lHJQ4rNeE

Hinweis: Bewahren Sie den API-Schlüssel sicher auf. Er wird benötigt, um die Tools in agorum core zu konfigurieren.

API-Keys auflisten

Um alle vorhandenen API-Schlüssel aufzulisten:

sudo /opt/albert-ai-sandbox-manager/scripts/api-key-manager.sh list

API-Key löschen

Um einen API-Schlüssel zu löschen:

sudo /opt/albert-ai-sandbox-manager/scripts/api-key-manager.sh delete <api-key>

Sicherheitshinweise

Integration mit agorum core und ALBERT | AI Agents

Um die ALBERT | AI Sandbox in agorum core zu nutzen, müssen Sie eine KI-Voreinstellung konfigurieren. Das Projekt agorum.ai.agents.library.basic enthält bereits eine vorkonfigurierte Voreinstellung.

Voraussetzungen

Konfiguration der KI-Voreinstellung

Gehen Sie wie folgt vor, um die vorkonfigurierte Sandbox-Voreinstellung einzurichten:

  1. Navigieren Sie in agorum core zu KI-Konfiguration > Voreinstellungen.
  2. Öffnen Sie die Voreinstellung agorum_ai_agents_library_basic_preset_albert_ai_sandbox mit dem Anzeigenamen ALBERT | AI Sandbox.
  3. Wählen Sie unter Referenz-Voreinstellung die KI-Voreinstellung mit der Verbindung zum gewünschen Sprachmodell aus.
  4. Aktivieren Sie die Option Diese Voreinstellung kann in ALBERTs Chat genutzt werden, wenn Sie die Sandbox im Chat verwenden möchten.
  5. Klicken Sie auf Tools und wählen Sie die Tool-Group All Sandbox-Tools (agorum_ai_agents_library_basic_sandbox_tools_group).
  6. Bearbeiten Sie das Tool Manages sandboxes on an ALBERT | AI Sandbox Server (agorum_ai_agents_library_basic_sandbox_manage):

    Base URL: Tragen Sie die Basis-URL des Sandbox-Servers ein (z.B. http://10.0.1.61 oder https://sandbox.example.com)
    API Key: Fügen Sie den im vorherigen Schritt erstellten API-Schlüssel ein
  7. Speichern Sie die Änderungen.

Hinweis: Die anderen Tools in der Tool-Group (upload, download, MCP) erben automatisch die Basis-URL und den API-Key vom Manage-Tool durch dynamische Parameter.

Verfügbare Tools

Technischer Name Kurzbeschreibung Dokumentation
sandbox_download Sicheres Herunterladen von Dateien aus ALBERT | AI Sandbox-Umgebungen und deren Speicherung als temporäre Dateien in agorum core Dokumentation
sandbox_upload Sicherer Upload von Dateien auf einen ALBERT | AI Sandbox Server zur isolierten Verarbeitung und Analyse durch KI-Systeme Dokumentation
sandbox_manage Verwaltung von ALBERT | AI Sandbox Server Containern Dokumentation
albert_ai_sandbox_mcp MCP-Tools für Shell-Befehle und Browser-Automatisierung (bash-mcp, playwright-browser) Dokumentation

Kontext und Wissensbasis

Die vorkonfigurierte Voreinstellung enthält bereits einen optimierten Kontext mit:

Test der Konfiguration

Um zu testen, ob die Integration funktioniert:

  1. Öffnen Sie den ALBERT Chat.
  2. Wählen Sie die Voreinstellung ALBERT | AI Sandbox aus.
  3. Geben Sie ein: Liste mir meine Container auf
  4. Die KI sollte eine Liste der vorhandenen Container zurückgeben (oder eine leere Liste, wenn noch keine Container existieren).

Chat-Vorlagen

Zusätzlich zu den KI-Voreinstellungen können Sie Chat-Vorlagen erstellen, die Ihren Nutzern den Umgang mit den Sandboxen erleichtern, siehe Die Chat-Vorlagen verwenden.

Arbeiten mit Sandboxen

Dieser Abschnitt beschreibt den typischen Workflow bei der Arbeit mit Sandboxen und gibt Best Practices für die effiziente Nutzung.

Sandbox-Lifecycle

Eine Sandbox durchläuft verschiedene Zustände während ihrer Lebensdauer:

  1. Create: Erstellen Sie eine neue Sandbox mit dem create-Befehl. Die KI erstellt einen neuen Docker-Container mit vollständigem Desktop und allen Tools.
  2. Running: Nach der Erstellung ist die Sandbox aktiv und bereit für Aufgaben. Sie können Shell-Befehle ausführen, Dateien hochladen/herunterladen und den Browser steuern.
  3. Idle: Wenn 10 Minuten lang keine Aktivität stattfindet, wird der Container automatisch gestoppt, um Ressourcen zu sparen.
  4. Stopped: Ein gestoppter Container kann jederzeit mit start wieder aktiviert werden. Alle Daten bleiben erhalten.
  5. Removed: Mit remove wird der Container permanent gelöscht. Alle Daten gehen verloren.

Empfohlener Workflow

Die KI führt automatisch folgenden Workflow aus, wenn Sie eine Aufgabe übergeben:

  1. Container prüfen: Die KI listet zuerst alle vorhandenen Container auf (list).
  2. Container auswählen oder erstellen:

    • Wenn genau ein Container existiert: Dieser wird verwendet
    • Wenn mehrere Container existieren: Die KI fragt, welcher verwendet werden soll
    • Wenn kein Container existiert: Ein neuer wird erstellt
  3. Status prüfen: Die KI prüft den Status des ausgewählten Containers.
  4. Container starten: Falls gestoppt, wird der Container automatisch gestartet.
  5. Aufgabe ausführen: Die KI führt die Aufgabe aus (Dateien verarbeiten, Browser steuern, Skripte ausführen).
  6. Ergebnisse zurückgeben: Erzeugte Dateien werden nach agorum core heruntergeladen und dem Benutzer bereitgestellt.

Container-Verwaltung

Jeder Benutzer kann mehrere Container parallel betreiben. Die Container werden automatisch in der Benutzerkonfiguration unter home:MyAdmin/agorum.ai/settings/sandbox.json gespeichert.

Wichtige Hinweise:

Automatisches Container-Management

Um Ressourcen zu schonen, werden Container automatisch nach 10 Minuten Inaktivität gestoppt. Dies betrifft:

Tipp: Gestoppte Container verbrauchen keine CPU oder RAM, belegen aber weiterhin Festplattenspeicher. Löschen Sie nicht mehr benötigte Container mit dem remove-Befehl.

Best Practices

Container-Namen vergeben

Verwenden Sie sprechende Namen für Ihre Container, um sie leichter identifizieren zu können:

"Erstelle einen Container mit dem Namen 'webautomation'"

Dateien strukturiert ablegen

Hochgeladene Dateien werden standardmäßig unter /tmp gespeichert. Organisieren Sie Ihre Dateien in Unterverzeichnissen:

mkdir -p /tmp/projekt1/eingaben
mkdir -p /tmp/projekt1/ausgaben

Ressourcen freigeben

Löschen Sie Container, die Sie nicht mehr benötigen:

"Lösche meinen Container 'webautomation'"

Desktop für komplexe Interaktionen

Für Aufgaben, die manuelle Interaktion erfordern (etwa Multi-Faktor-Authentifizierung), können Sie den Desktop-Link verwenden:

"Gib mir den anklickbaren Link zu meinem Container-Desktop"

MCP-Services in der Sandbox

Jede Sandbox enthält einen MCP Hub (Model Context Protocol), der umfangreiche Tools für Shell-Befehle und Browser-Automatisierung bereitstellt. Diese Tools werden automatisch durch das Tool albert_ai_sandbox_mcp verfügbar gemacht.

Shell-Execution Tools

Die bash-mcp Tools ermöglichen die Ausführung von Shell-Befehlen direkt im Container:

Tool Beschreibung
bash-mcp-run Führt einen Shell-Befehl aus und gibt die Ausgabe zurück.
Parameter:
  • command: Auszuführender Befehl
  • cwd: Arbeitsverzeichnis (optional, Standard: /tmp)
  • timeout: Timeout in Millisekunden (Standard: 30000)
Beispiele: Dateikonvertierung, Skript-Ausführung, Systemabfragen
bash-mcp-run_background Startet einen Befehl im Hintergrund.
Parameter:
  • command: Auszuführender Befehl
  • name: Eindeutiger Name für den Prozess
  • cwd: Arbeitsverzeichnis (optional)
Beispiele: Webserver starten, Langzeitprozesse
bash-mcp-kill_background Beendet einen Hintergrundprozess.
Parameter:
  • name: Name des zu beendenden Prozesses
bash-mcp-list_background Listet alle laufenden Hintergrundprozesse auf.

Browser-Automation Tools (Playwright)

Die playwright-browser Tools ermöglichen vollständige Browser-Automatisierung mit Chromium:

Navigation und Seitensteuerung

Tool Beschreibung
playwright-browser_navigate Navigiert zu einer URL.
Parameter: url (URL der aufzurufenden Webseite)
playwright-browser_navigate_back Geht zurück zur vorherigen Seite.
playwright-browser_tabs Verwaltet Browser-Tabs (list, new, close, select).
Parameter:
  • action: Operation (list, new, close, select)
  • index: Tab-Index für close/select (optional)
playwright-browser_close Schließt die aktuelle Seite.
playwright-browser_resize Passt die Browsergröße an.
Parameter: width, height (in Pixel)

Interaktion mit Elementen

Tool Beschreibung
playwright-browser_click Klickt auf ein Element.
Parameter:
  • element: Beschreibung des Elements
  • ref: Referenz aus dem Snapshot
  • button: Maustaste (left, right, middle)
  • doubleClick: Doppelklick (boolean)
  • modifiers: Modifier-Tasten (Alt, Control, Shift)
playwright-browser_type Gibt Text in ein Element ein.
Parameter:
  • element, ref: Element-Identifikation
  • text: Einzugebender Text
  • submit: Enter nach Eingabe drücken (boolean)
  • slowly: Zeichen für Zeichen eingeben (boolean)
playwright-browser_fill_form Füllt mehrere Formularfelder aus.
Parameter: Array von Feldern mit name, type, ref und value
playwright-browser_select_option Wählt Optionen in Dropdown-Menüs aus.
Parameter: element, ref, values (Array)
playwright-browser_hover Bewegt die Maus über ein Element.
playwright-browser_drag Drag & Drop zwischen zwei Elementen.
Parameter: startElement, startRef, endElement, endRef
playwright-browser_press_key Drückt eine Taste.
Parameter: key (z.B. "Enter", "ArrowLeft", "a")

 

Seitenanalyse und Informationsgewinnung

Tool Beschreibung
playwright-browser_snapshot Erstellt einen barrierefreien Snapshot der Seite mit strukturierten Element-Referenzen.
Wichtig: Dies ist die bevorzugte Methode zur Seitenanalyse - besser als Screenshots!
playwright-browser_take_screenshot Erstellt einen Screenshot der Seite oder eines Elements.
Parameter:
  • type: png oder jpeg
  • filename: Dateiname (optional)
  • element, ref: Spezifisches Element (optional)
  • fullPage: Gesamte Seite (boolean)

Hinweis: Für Aktionen verwenden Sie browser_snapshot!

playwright-browser_console_messages Gibt alle Konsolen-Nachrichten seit Laden der Seite zurück.
playwright-browser_network_requests Gibt alle Netzwerk-Anfragen seit Laden der Seite zurück.
playwright-browser_evaluate Führt JavaScript-Code auf der Seite oder in einem Element aus.
Parameter:
  • function: JavaScript-Funktion als String
  • element, ref: Element (optional)

 

Datei-Upload und Dialoge

Tool Beschreibung
playwright-browser_file_upload Lädt eine oder mehrere Dateien hoch.
Parameter: paths (Array von absoluten Pfaden)

Hinweis: Dateien müssen zuerst mit sandbox_upload in den Container geladen werden!

playwright-browser_handle_dialog Behandelt Browser-Dialoge (alerts, confirms, prompts).
Parameter:
  • accept: Dialog bestätigen (boolean)
  • promptText: Text für Prompt (optional)

Hilfsfunktionen

Tool Beschreibung
playwright-browser_wait_for Wartet auf bestimmte Bedingungen.
Parameter:
  • time: Wartezeit in Sekunden (optional)
  • text: Warten bis Text erscheint (optional)
  • textGone: Warten bis Text verschwindet (optional)
playwright-browser_install Installiert den Browser (falls noch nicht vorhanden).
Hinweis: Normalerweise nicht nötig, Browser ist vorinstalliert.

Beispiel-Workflows mit MCP

Webseite aufrufen und Daten extrahieren

  1. playwright-browser_navigate zu https://example.com
  2. playwright-browser_snapshot erstellen
  3. playwright-browser_evaluate um Daten zu extrahieren
  4. Ergebnisse in Datei speichern und mit sandbox_download herunterladen

 

Formular ausfüllen und absenden

  1. playwright-browser_navigate zur Formularseite
  2. playwright-browser_snapshot erstellen (Element-Referenzen abrufen)
  3. playwright-browser_fill_form mit allen Feldern
  4. playwright-browser_click auf Submit-Button
  5. playwright-browser_wait_for bis Bestätigung erscheint

 

Datei verarbeiten und hochladen

  1. sandbox_upload - Datei in Container laden
  2. bash-mcp-run - Datei mit Shell-Befehlen verarbeiten
  3. playwright-browser_navigate zur Upload-Seite
  4. playwright-browser_file_upload mit verarbeiteter Datei

Automatischer Desktop-Zugriff

Jede Sandbox enthält einen vollständigen Linux-Desktop, der über noVNC im Browser zugänglich ist. Dies ermöglicht visuelle Interaktion mit dem Container, wenn automatisierte Prozesse nicht ausreichen.

Desktop-Funktionen

Der Desktop in jeder Sandbox bietet:

Zugriff auf den Desktop

Der Desktop ist über eine eindeutige URL erreichbar. Nach dem Erstellen eines Containers erhalten Sie die Desktop-URL:

http://<sandbox-server>/<container-name>/

Beispiel:

http://10.0.1.61/sbx-abc123/

Sie können die URL auch jederzeit von der KI erfragen:

"Gib mir den Link zum Desktop meines Containers"

noVNC-Bedienung

Der Desktop wird über noVNC bereitgestellt, einen browserbasierten VNC-Client:

Anwendungsfälle für manuellen Desktop-Zugriff

Anwendungsfall Beschreibung
Multi-Faktor-Authentifizierung Wenn eine Webseite 2FA verlangt, können Sie im Desktop-Browser den Code eingeben oder eine Authentifizierungs-App verwenden.
Visuelle Prüfung Überprüfen Sie, wie eine Webseite dargestellt wird, oder kontrollieren Sie das Ergebnis einer Browser-Automation visuell.
Debugging Untersuchen Sie Fehler bei der Automatisierung durch direktes Nachvollziehen der Schritte im Browser.
Manuelle Downloads Laden Sie Dateien manuell herunter, wenn Automatisierung nicht möglich ist (z.B. CAPTCHA).
Datei-Überprüfung Öffnen Sie erzeugte Dateien im Container, um das Ergebnis vor dem Download zu prüfen.

Automatisches Herunterfahren

Wenn für 10 Minuten keine Aktivität stattfindet (weder API-Aufrufe noch Desktop-Nutzung), wird der Container automatisch gestoppt. Der Desktop bleibt dabei erhalten:

Tipp: Sie können den Desktop parallel zur KI-Automatisierung nutzen. Öffnen Sie einfach die Desktop-URL in einem neuen Tab, während die KI im Hintergrund arbeitet.

Anwendungsbeispiele

Dieser Abschnitt zeigt typische Anwendungsfälle für ALBERT | AI Sandbox und wie Sie diese in der Praxis umsetzen.

Beispiel 1: Webseite aufrufen und Cookie-Banner bestätigen

Aufgabe an die KI:

"Öffne https://www.agorum.com im Browser und klicke auf dem Cookie-Banner auf 'Einstellung speichern'"

Was passiert:

  1. KI erstellt oder startet einen Container
  2. playwright-browser_navigate zu www.agorum.com
  3. playwright-browser_snapshot erstellt Seitenstruktur
  4. playwright-browser_click auf Cookie-Button
  5. Bestätigung wird zurückgemeldet

Beispiel 2: Formular ausfüllen

Aufgabe an die KI:

"Fülle das Kontaktformular auf example.com aus mit:
Name: Max Mustermann
E-Mail: max@example.com
Nachricht: Dies ist ein Test"

Ergebnis: Die KI navigiert zur Seite, identifiziert alle Formularfelder und füllt sie automatisch aus.

Beispiel 3: SVG zu PNG konvertieren

Aufgabe an die KI (mit angehängter SVG-Datei):

"Konvertiere diese SVG-Datei in ein PNG mit 1024 Pixeln für die längste Seite"

Was passiert:

  1. KI lädt die angehängte Datei mit sandbox_upload in den Container
  2. Führt bash-mcp-run mit ImageMagick-Befehl aus:
    convert input.svg -resize 1024x1024 output.png
  3. Lädt das Ergebnis mit sandbox_download zurück nach agorum core
  4. Gibt den Link zur konvertierten Datei zurück

Beispiel 4: Mehrere Bilder konvertieren

Aufgabe an die KI:

"Erstelle ein Bash-Skript, das alle PNG-Dateien in JPG konvertiert, und führe es aus"

Ergebnis: Die KI erstellt ein Skript, macht es ausführbar und führt es im Container aus.

Beispiel 5: API abfragen und Daten verarbeiten

Aufgabe an die KI:

"Erstelle ein Python-Skript, das die API https://api.example.com/data abfragt,
die JSON-Antwort verarbeitet und als CSV-Datei speichert"

Was passiert:

  1. KI erstellt Python-Skript mit requests und pandas
  2. Speichert Skript im Container
  3. Führt Skript mit bash-mcp-run aus
  4. Lädt resultierende CSV-Datei herunter

Beispiel 6: Web Scraping mit Datenverarbeitung

Aufgabe an die KI:

"Rufe https://example.com/produkte auf, extrahiere alle Produktnamen und Preise,
und erstelle eine Excel-Datei mit den Daten"

Workflow:

  1. playwright-browser_navigate zur Produktseite
  2. playwright-browser_snapshot für Seitenstruktur
  3. playwright-browser_evaluate zum Extrahieren der Daten
  4. Python-Skript erstellen zur Verarbeitung
  5. Excel-Datei mit openpyxl generieren
  6. Datei herunterladen

Beispiel 7: Dokument hochladen und verarbeiten

Aufgabe an die KI (mit angehängtem PDF):

"Lade dieses PDF auf upload.example.com hoch und lade das verarbeitete Ergebnis herunter"

Workflow:

  1. sandbox_upload: PDF in Container laden
  2. playwright-browser_navigate zur Upload-Seite
  3. playwright-browser_file_upload: PDF hochladen
  4. playwright-browser_wait_for: Auf Verarbeitung warten
  5. playwright-browser_click: Download-Link klicken
  6. Datei im Container finden und mit sandbox_download herunterladen

Tipps für effektive Nutzung

Best Practices:

  • Klare Anweisungen: Geben Sie präzise an, was gemacht werden soll
  • Ziel definieren: Beschreiben Sie das gewünschte Endergebnis
  • Start-URL angeben: Nennen Sie die vollständige URL bei Web-Aufgaben
  • Dateinamen spezifizieren: Geben Sie an, wie Ausgabedateien heißen sollen
  • Format wählen: Spezifizieren Sie das gewünschte Ausgabeformat (CSV, Excel, JSON, etc.)