Zum Hauptinhalt springen

Erste Schritte

Diese Anleitung führt Sie Schritt für Schritt durch die Einrichtung des OpenAI Agents Manager Plugins.

Übersicht: Was Sie erwartet​

In 5 einfachen Schritten sind Sie startklar:

  1. ✅ Plugin installieren und aktivieren
  2. ✅ OpenAI API-Schlüssel erstellen
  3. ✅ API-Schlüssel in Shopware hinterlegen
  4. ✅ Ersten Agenten erstellen
  5. ✅ Agenten testen

Zeitaufwand: Ca. 15-20 Minuten

Schritt 1: Plugin installieren​

Installation über den Shopware Store​

  1. Melden Sie sich im Shopware-Backend an
  2. Navigieren Sie zu Erweiterungen → Meine Erweiterungen
  3. Suchen Sie nach "OpenAI Agents Manager" oder "5 Elements"
  4. Klicken Sie auf Installieren
  5. Nach der Installation klicken Sie auf Aktivieren

Installation über die Konsole​

Alternativ können Sie das Plugin per Kommandozeile installieren:

# Plugin installieren
bin/console plugin:install FelOAIAssistantsManager --activate

# Cache leeren
bin/console cache:clear
Plugin erfolgreich installiert

Nach der Aktivierung erscheint ein neuer Menüpunkt "5E OAI Agent Manager" in der linken Navigation Ihres Shopware-Backends.

Schritt 2: OpenAI API-Schlüssel erstellen​

Um das Plugin zu nutzen, benötigen Sie einen API-Schlüssel von OpenAI.

2.1 OpenAI-Konto erstellen (falls noch nicht vorhanden)​

  1. Besuchen Sie platform.openai.com
  2. Klicken Sie auf Sign Up (Registrieren)
  3. Erstellen Sie ein Konto oder melden Sie sich mit Google/Microsoft an
  4. Verifizieren Sie Ihre E-Mail-Adresse

2.2 Zahlungsmethode hinterlegen​

OpenAI arbeitet nach dem Pay-as-you-go Prinzip. Sie zahlen nur für das, was Sie nutzen.

  1. Gehen Sie zu platform.openai.com/settings/organization/billing
  2. Klicken Sie auf Add payment method
  3. Hinterlegen Sie eine Kreditkarte
  4. (Optional) Legen Sie ein monatliches Budget fest (z.B. 20€)
Kosten-Tipp

Für einen kleinen bis mittleren Shop reichen oft 10-20€ pro Monat. Dank Token-Caching (50-90% Ersparnis) sind die Kosten sehr überschaubar!

2.3 API-Schlüssel erstellen​

  1. Navigieren Sie zu platform.openai.com/api-keys
  2. Klicken Sie auf + Create new secret key
  3. Geben Sie einen Namen ein (z.B. "Shopware Production")
  4. Wählen Sie die Berechtigungen: All (Alle)
  5. Klicken Sie auf Create secret key
Wichtig: Schlüssel sicher aufbewahren!

Der API-Schlüssel wird nur einmal angezeigt! Kopieren Sie ihn sofort und speichern Sie ihn sicher. Falls Sie ihn verlieren, müssen Sie einen neuen erstellen.

Der Schlüssel sieht so aus:

sk-proj-aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890...

Kopieren Sie den kompletten Schlüssel in die Zwischenablage.

Schritt 3: API-Schlüssel in Shopware hinterlegen​

Jetzt verbinden wir Shopware mit Ihrem OpenAI-Konto.

3.1 Plugin-Konfiguration öffnen​

  1. Gehen Sie im Shopware-Backend zu Einstellungen → System → Plugins
  2. Suchen Sie das Plugin OpenAI Agents Manager
  3. Klicken Sie auf die drei Punkte (⋮) rechts
  4. Wählen Sie Konfigurieren

3.2 API-Schlüssel eintragen​

Im Konfigurationsfenster:

  1. Finden Sie das Feld "API Key for the Agent Manager"
  2. Fügen Sie Ihren kopierten API-Schlüssel ein
  3. Klicken Sie auf "Test API Key" (falls verfügbar)
  4. Klicken Sie auf Speichern
API-Verbindung hergestellt

Wenn alles geklappt hat, sehen Sie eine Erfolgsmeldung. Ihr Shopware-System kann jetzt mit OpenAI kommunizieren!

3.3 Weitere Einstellungen (Optional)​

In der Plugin-Konfiguration finden Sie weitere Optionen:

EinstellungEmpfehlungBeschreibung
Thread-Logging aktivieren✅ AnSpeichert alle Chat-Verläufe zur Nachverfolgung
Nutzungszähler aktivieren✅ AnZählt Tool-Aufrufe pro Agent
Suchanfragen-Logging✅ AnProtokolliert Agent-Suchanfragen
Maximale Versuche75Anzahl Versuche bevor Abbruch
Wartezeit zwischen Versuchen2 SekundenWartezeit in der Schleife

Für den Anfang können Sie die Standardeinstellungen beibehalten.

Schritt 4: Ersten Agenten erstellen​

Jetzt erstellen wir Ihren ersten Agenten! Wir beginnen mit einem einfachen Produktberater.

4.1 Agent-Übersicht öffnen​

  1. Klicken Sie in der linken Navigation auf 5E OAI Agent ManagerAgenten-Übersicht
  2. Sie sehen die Agent-Übersicht (noch leer)
  3. Klicken Sie auf + Create Agent (Agenten erstellen)

4.2 Agent Name eingeben​

Geben Sie einen internen Namen für Ihren Agenten ein:

Agent Name (für interne Verwaltung):

Produktberater Shop

Dieser Name wird nur im Backend angezeigt und dient zur Unterscheidung mehrerer Agenten.

4.3 Instructions - Das MCP-Interface für Shopware​

Was sind Instructions?

Die Instructions sind voroptimierte Systemprompts, die dem Agenten mitteilen, wie er die verfügbaren Tools nutzen soll. Zusammen mit den Tools erhalten Sie quasi ein MCP (Model Context Protocol) - eine strukturierte Schnittstelle zur Steuerung Ihres Shopware-Shops!

Das Plugin liefert bereits optimierte Instructions mit, die:

  • ✅ HTML-formatierte Antworten erzeugen (statt Markdown)
  • ✅ Intelligente Produktsuche mit exaktem Matching von Kategorien und Properties
  • ✅ Log-System als Wissensdatenbank nutzen
  • ✅ Mehrsprachigkeit automatisch handhaben
  • ✅ Sicherheitsprotokoll implementieren (Protocol 712 - keine User-URLs fetchen)

Verfügbare Tools (aktivierbar im nächsten Schritt):

  • get_product_properties() - Kategorien, Properties, Hersteller abrufen
  • product_search() - Produkte mit Filtern suchen (Preis, Kategorie, Properties)
  • get_meta_information() - Shop-Metadaten
  • search_logs() - Wissensdatenbank durchsuchen
  • fetch_url() - Sichere URL-Abfragen
  • Weitere Tools für Warenkorb, Bestellungen, CMS-Seiten, etc.

Workflow-Beispiel (aus den Instructions):

User: "Ich suche eine Jacke in Blau zwischen 50-100€"

Agent denkt:
1. get_product_properties() → Holt verfügbare Kategorien & Farben
2. product_search(
     query: "Jacke",
     categories: ["Bekleidung", "Oberbekleidung"],
     properties: ["Farbe:Blau"],
     price_min: 50,
     price_max: 100
   )
3. Formatiert Ergebnisse als HTML-Liste mit Links
Anpassbar

Die Instructions sind optimiert, können aber jederzeit angepasst werden, wenn Sie spezifisches Verhalten wünschen. Für den Start empfehlen wir die Standardversion!

4.4 Modell auswählen​

Wählen Sie ein KI-Modell:

Für den Einstieg empfohlen: gpt-4o-mini

  • ✅ Sehr günstig (ca. 10x günstiger als GPT-4o)
  • ✅ Schnelle Antworten (1-3 Sekunden)
  • ✅ Ausreichend für die meisten Anwendungen

Sie können später jederzeit zu einem leistungsstärkeren Modell wechseln.

GPT-4o vs. GPT-5 Instructions

Das Plugin enthält optimierte Instructions für beide Modellgenerationen. GPT-5 Modelle (gpt-5-mini, gpt-5) nutzen fortgeschrittene Reasoning-Fähigkeiten und strukturiertere Tool-Aufrufe.

4.5 Tools aktivieren - Die MCP-Schnittstelle​

Tools sind die eigentliche Macht des Systems! Sie geben dem Agenten strukturierten Zugriff auf Shopware-Funktionen.

Für einen Produktberater-Agenten empfohlen:

Basis-Tools (unbedingt aktivieren):

  • ✅ get_product_properties() - Pflicht! Holt Kategorien, Properties, Hersteller
  • ✅ product_search() - Produktsuche mit Filtern
  • ✅ get_chatbot_name() - Name des Bots für Begrüßungen

Erweiterte Produkt-Tools:

  • ✅ get_product_details() - Detaillierte Produktinfos
  • ✅ get_categories() - Kategoriebaum
  • ✅ get_manufacturer() - Hersteller-Informationen

Wissensdatenbank:

  • ✅ search_logs() - Durchsucht Ihre FAQ/Wissensdatenbank
  • ✅ tags_for_logs() - Verfügbare Tags für Log-Suche
  • ✅ get_meta_information() - Shop-Metadaten

Optionale Tools (je nach Anwendungsfall):

  • fetch_url() - Sichere URL-Abfragen (nur für vertrauenswürdige Quellen)
  • add_to_cart() - Produkte in Warenkorb legen
  • get_cart() - Warenkorb anzeigen
  • Weitere CMS & Content-Tools
Wichtig: Tool-Reihenfolge

Die Instructions sind darauf optimiert, zuerst get_product_properties() aufzurufen, bevor eine Produktsuche erfolgt. So weiß der Agent, welche Kategorien und Properties existieren und kann exakt matchen!

MCP-Konzept

Model Context Protocol: Die Kombination aus Instructions + Tools gibt der KI eine strukturierte, sichere Schnittstelle zum Shop. Sie kann:

  • Daten abrufen (get_product_properties, search_logs)
  • Daten filtern (product_search mit exakten Parametern)
  • Daten verarbeiten (HTML-formatierte Antworten)

Aber sie kann keine schädlichen Aktionen durchführen (z.B. keine beliebigen URLs fetchen - Protocol 712).

4.6 Einstellungen anpassen​

Temperature (Kreativität): 0.7

  • 0.1 = sehr vorhersehbar und konsistent
  • 1.5 = kreativ und variabel

Reasoning Effort: medium

  • Low = schnell, einfach
  • Medium = ausgewogen (empfohlen)
  • High = gründlich, langsam

Lassen Sie die anderen Einstellungen auf Standard.

4.7 Agent aktivieren und speichern​

  1. Setzen Sie "Is Active" auf ✅ An
  2. (Optional) Setzen Sie "Is Default" auf ✅ An (falls dies Ihr Haupt-Agent sein soll)
  3. Klicken Sie auf Speichern
Erster Agent erstellt! 🎉

Ihr Agent "Produktberater" ist jetzt einsatzbereit!

Schritt 5: Agenten testen​

Jetzt testen wir, ob alles funktioniert.

5.1 Backend-Chat öffnen​

  1. Klicken Sie in der linken Navigation auf 5E OAI Agent Manager
  2. Klicken Sie im Menü auf Chat
  3. Der Backend-Chat wird geöffnet

5.2 Ersten Test durchführen​

Probieren Sie diese Test-Nachrichten:

Test 1: Begrüßung

Hallo!

Erwartung: Der Agent begrüßt Sie freundlich

Test 2: Produktsuche

Ich suche eine Jacke

Erwartung: Der Agent fragt nach weiteren Details (Farbe, Größe, Budget)

Test 3: Spezifische Suche (wenn Sie Jacken im Shop haben)

Zeig mir bitte schwarze Winterjacken unter 100€

Erwartung: Der Agent sucht und präsentiert passende Produkte

5.3 Konversation analysieren​

Achten Sie darauf:

  • ✅ Antwortet der Agent schnell? (sollte 1-5 Sekunden dauern)
  • ✅ Ist die Antwort freundlich und hilfreich?
  • ✅ Werden die Tools korrekt aufgerufen?
  • ✅ Sind die Produktempfehlungen relevant?

Troubleshooting: Häufige Probleme​

Problem: "Missing OpenAI API Key"​

Lösung:

  1. Gehen Sie zu Einstellungen → System → Plugins
  2. Konfigurieren Sie das Plugin erneut
  3. Prüfen Sie, ob der API-Schlüssel vollständig kopiert wurde

Problem: Agent antwortet nicht​

Mögliche Ursachen:

  • ❌ API-Schlüssel ungültig → Neuen Schlüssel erstellen
  • ❌ Kein OpenAI-Guthaben → Guthaben aufladen
  • ❌ Agent nicht aktiviert → In Agent-Einstellungen "Is Active" setzen

Problem: "Rate limit exceeded"​

Lösung: OpenAI hat ein Anfrage-Limit. Warten Sie 1 Minute und versuchen Sie es erneut.

Problem: Hohe Kosten​

Lösung:

  • Nutzen Sie gpt-4o-mini statt teurerer Modelle
  • Deaktivieren Sie nicht benötigte Tools
  • Kürzen Sie Instructions (aber nicht zu sehr!)

Nächste Schritte​

Glückwunsch! Sie haben erfolgreich:

  • ✅ Das Plugin installiert
  • ✅ Die OpenAI-Verbindung hergestellt
  • ✅ Ihren ersten Agenten erstellt
  • ✅ Den Agenten getestet

Jetzt geht es weiter mit:

➡️ Agenten-Konfiguration verstehen - Detaillierte Erklärung aller Einstellungen

➡️ Tools & Funktionen - Welches Tool wofür?

➡️ Vector Stores nutzen - Eigene Dokumente hochladen

➡️ Best Practices - Tipps für optimale Agenten