🔧 Benutzeranleitung: API Integration

Tools vs. Nodes

1. OpenAPI-Spezifikation vorbereiten

1. Datei beschaffen: Laden Sie eine OpenAPI 3.x Datei (YAML oder JSON)
2. Qualität prüfen: Vollständige Parameter-Definitionen vorhanden?
3. Authentifizierung: Security-Schemas definiert?
4. Base URL: Server-URLs korrekt angegeben?

2. OpenAPI-Datei hochladen

1. Navigation: Gehen Sie zu API Tools → OpenAPI hochladen
2. Datei auswählen: Ziehen Sie die Datei ins Upload-Feld oder wählen Sie sie aus
3. Validierung: Das System analysiert automatisch die Spezifikation
4. Übersicht: Prüfen Sie die erkannten Endpunkte und Parameter
5. Speichern: Bestätigen Sie den Upload

🛠️ Tool erstellen

Schritt 1: Typ auswählen

1. Navigieren Sie zu API Tools → Konfigurationen → Neue Konfiguration
2. Wählen Sie "Tool" für mehrteilige API-Workflows
3. Klicken Sie auf "Weiter zur Endpunkt-Auswahl"

Schritt 2: OpenAPI-Spezifikation wählen

1. Wählen Sie eine hochgeladene OpenAPI-Spezifikation
2. Überprüfen Sie Anzahl der verfügbaren Endpunkte
3. Prüfen Sie Base URL und Version
4. Klicken Sie auf "Weiter zur Typ-Auswahl"

Schritt 3: Endpunkte auswählen

• Mehrfachauswahl: Wählen Sie bis zu 20 Endpunkte
• Verwandte Endpunkte: Kombinieren Sie logisch zusammengehörige APIs
• Parameter prüfen: Achten Sie auf Pflichtparameter
• Authentifizierung: Prüfen Sie Auth-Methoden

Schritt 4: Konfiguration

🧱 Node erstellen

Unterschiede zu Tools

• Ein Endpunkt: Radio-Button statt Checkboxen
• Fokussierte Konfiguration: Weniger komplex
• Workflow-Integration: Direkt als Baustein verwendbar
• Schnelle Erstellung: Weniger Konfigurationsschritte

Besondere Merkmale

• Request-Rekonstruktion: Vollständige HTTP-Requests aus Konfiguration
• Parameter-Validierung: Typen, Required-Felder, Enum-Werte
• Live-Testing: Direkte API-Ausführung
• Request-Preview: Vor Ausführung ansehen

Live-Testing durchführen

Node Testing

1. Node Details öffnen: Klicken Sie auf "Details & Test"
2. Parameter eingeben: Füllen Sie alle Pflichtfelder aus
3. Authentifizierung: Wählen Sie Auth-Methode und geben Credentials ein
4. Request Body: JSON für POST/PUT Requests
5. Vorschau: Klicken Sie "Request-Vorschau" für HTTP-Details
6. Ausführen: "Request ausführen" für Live-Test

Tool Testing

• Einzeln testen: Jeder Endpunkt separat testbar
• Batch-Test: "Alle Endpunkte testen" Funktion
• Konfiguration überprüfen: Validierung vor Test
• Export: Test-Ergebnisse exportierbar

Konfigurationsvalidierung

Automatische Prüfungen

• Parameter-Vollständigkeit: Alle Required-Parameter definiert?
• Auth-Konsistenz: Authentifizierung korrekt konfiguriert?
• Schema-Kompatibilität: Request/Response Schemas gültig?
• URL-Validierung: Base URLs erreichbar?

Validierungsergebnisse

Tools in KI-Agenten einbinden

Voraussetzungen

• Gültige Konfiguration: Tool erfolgreich validiert
• Beschreibungen: Aussagekräftige Endpunkt-Beschreibungen
• Authentifizierung: Funktionierende Auth-Konfiguration
• Testing: Mindestens einmal erfolgreich getestet

Integration-Schritte

1. Agent konfigurieren: Gehen Sie zur Agenten-Verwaltung
2. Tools zuweisen: Wählen Sie Ihr erstelltes Tool aus
3. Berechtigungen: Definieren Sie Nutzungsrechte
4. Kontext bereitstellen: Erklären Sie dem Agenten die Tool-Verwendung
5. Testing: Testen Sie die Agent-Tool-Interaktion

Nodes in Workflows verwenden

Workflow-Baustein

• Drag & Drop: Node direkt in Workflow-Designer ziehen
• Parameter-Mapping: Workflow-Variablen mit Node-Parametern verbinden
• Conditional Logic: Response-basierte Workflow-Verzweigungen
• Error Handling: Fehlerbehandlung für API-Aufrufe

Datenfluss

1. Input-Mapping: Workflow-Daten → Node-Parameter
2. API-Aufruf: Node führt HTTP-Request aus
3. Response-Processing: Antwort wird verarbeitet
4. Output-Mapping: Ergebnis → Workflow-Variablen
5. Flow-Control: Nächster Workflow-Schritt

📊 Beispiel 1: CRM-Integration Tool

1. OpenAPI beschaffen: CRM-System API-Dokumentation laden
2. Endpunkte auswählen: GET /contacts, POST /contacts, PUT /contacts/{id}, DELETE /contacts/{id}
3. Tool konfigurieren: Namen "CRM Contact Management", OAuth2 Authentifizierung
4. Beschreibungen:
   • GET: "Kontakte suchen und auflisten"
   • POST: "Neue Kontakte erstellen"
   • PUT: "Bestehende Kontakte aktualisieren"
   • DELETE: "Kontakte löschen"
5. Testing: Alle CRUD-Operationen testen
6. Agent-Integration: Tool dem Customer Service Agent zuweisen
7. Kontext: "Verwende dieses Tool für alle Kundendaten-Operationen"

🌤️ Beispiel 2: Wetter-API Node

1. Simple API: Weather API mit GET /weather/{city} Endpunkt
2. Node erstellen: Einen Endpunkt auswählen
3. Parameter konfigurieren: city (required), units (optional)
4. API Key Auth: Header "X-API-Key" konfigurieren
5. Testing: Mit verschiedenen Städten testen
6. Workflow-Integration: Als Baustein in "Tagesplanung-Workflow"
7. Logik: Wetterabfrage → Entscheidung → Terminplanung

🔗 Beispiel 3: Multi-Service Integration

1. Szenario: E-Commerce Fulfillment-Prozess
2. Service 1: Inventory API (Node für Lagerbestand)
3. Service 2: Payment API (Node für Zahlungsabwicklung)
4. Service 3: Shipping API (Tool mit Tracking, Labeling, etc.)
5. Workflow-Design:
   • Inventory Check → Payment Processing → Shipping Creation
   • Error-Handling für jeden API-Aufruf
   • Conditional Flows basierend auf Responses
6. Testing: End-to-End Workflow-Test
7. Monitoring: API-Performance überwachen

API-Performance verbessern

🔍 Request-Rekonstruktion

Das System kann aus gespeicherten Konfigurationen vollständige HTTP-Requests aufbauen:

• URL-Building: Base URL + Path + Query Parameters
• Header-Generation: Auth-Header + Content-Type + Custom
• Body-Construction: JSON/XML-Body aus Schema
• Method-Mapping: Korrekte HTTP-Methode

POST https://api.example.com/v1/users
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin"
}

✅ Parameter-Validierung

Automatische Validierung basierend auf OpenAPI-Schema: