Eigene Aktionen
Mit eigenen Aktionen ruft Ihr KI-Agent jede beliebige REST-API auf — zum Beispiel um ein Ticket in Ihrem Helpdesk anzulegen, einen Datensatz im CRM zu aktualisieren oder eine Bestellung auszulösen.
Was Sie erreichen werden
Nach dieser Anleitung können Sie:
- Eine eigene Aktion mit Endpunkt, Methode und Feldern definieren
- Den Ausführungszeitpunkt wählen und verstehen, wie er die Befüllung der Felder beeinflusst
- Verschachtelte JSON-Strukturen im Request Body aufbauen
- Pflichtfelder so absichern, dass das Zielsystem keine leeren Werte erhält
- Die Aktion mit einem Testanruf prüfen
Voraussetzungen
- Eine Integration vom Typ Custom API mit Basis-URL und Authentifizierung (Integrationen einrichten)
- Ein eingerichteter Agent (Agent erstellen)
Konzept: Integration und Aktion
Die Integration stellt die Verbindung her: Basis-URL und Zugangsdaten. Eine Aktion ist ein konkreter API-Aufruf innerhalb dieser Verbindung — ein Endpunkt mit Methode und Feldern. Eine Integration kann mehrere Aktionen enthalten, etwa Ticket anlegen und Kundenstatus abfragen gegen dieselbe API.
Schritt 1: Aktion anlegen
- Öffnen Sie in der Seitenleiste Agenten → Integrationen
- Klicken Sie an Ihrer Custom-API-Integration auf Aktionen
- Klicken Sie im Panel auf Neue Aktion hinzufügen
Es öffnet sich der Editor Neue Aktion mit den Abschnitten Basisinformationen, Prompt, API Konfiguration, Parameter Schema und Ausführungszeitpunkt.
Schritt 2: Basisinformationen und Prompt
| Feld | Eingabe |
|---|---|
| Name | Anzeigename der Aktion, z. B. Support-Ticket anlegen (mindestens 3 Zeichen) |
| Beschreibung | Optional: Kurze Beschreibung, was die Aktion tut |
| Anweisungen für den Agent | Wann und wie der Agent die Aktion im Gespräch verwenden soll (Pflichtfeld bei Ausführung während des Anrufs, mindestens 20 Zeichen) |
Der Prompt entscheidet, ob der Agent die Aktion zum richtigen Zeitpunkt auslöst. Beschreiben Sie konkret den Auslöser und welche Angaben der Agent vorher erfragen soll:
Verwende dieses Tool, wenn der Anrufer ein technisches Problem meldet.
Frage vorher nach: Name, Standort und einer kurzen Beschreibung des Problems.
Lege erst dann das Ticket an.
Schritt 3: API konfigurieren
Im Abschnitt API Konfiguration definieren Sie den Endpunkt:
| Feld | Eingabe |
|---|---|
| Tool Name | Technischer Name, z. B. create_ticket — nur Buchstaben, Zahlen und Unterstriche |
| HTTP Method | GET, POST, PUT, PATCH oder DELETE |
| API Pfad | Pfad hinter der Basis-URL der Integration, z. B. v1/tickets — über Volle URL eingeben können Sie alternativ eine komplette URL angeben |
| Tool Beschreibung | Was macht dieses Tool? Hilft dem Agenten bei der Auswahl |
| Response Timeout (Sekunden) | Maximale Wartezeit auf die API-Antwort, 5–120 Sekunden (Standard: 10) |
Schritt 4: Felder definieren
Im Abschnitt Parameter Schema legen Sie fest, welche Daten an die API gesendet werden — in drei Reitern: Headers, Query Parameters und Request Body. Klicken Sie auf Parameter hinzufügen und markieren Sie über die Checkbox links, welche Felder Pflichtfelder sind.
Für jedes Feld wählen Sie, woher der Wert kommt:
| Wert-Typ | Verhalten |
|---|---|
| LLM wählt | Der Agent ermittelt den Wert aus dem Gespräch — anhand der Feld-Beschreibung |
| Konstanter Wert | Ein fester Wert, der bei jedem Aufruf identisch gesendet wird |
| Dynamische Variable | Ein Wert aus dem Anruf-Kontext, z. B. Vorname des Kontakts oder die Anrufernummer |
Hinweis: Bei LLM wählt ist die Feld-Beschreibung entscheidend. Schreiben Sie genau hinein, was erwartet wird — z. B.
Kurze Zusammenfassung des Anliegens in einem Satzstatt nurBeschreibung.
Verschachteltes JSON
Im Reiter Request Body können Felder den Typ Objekt haben und eigene Unterfelder enthalten. Damit bauen Sie verschachtelte JSON-Strukturen auf, wie sie viele Ticket- und CRM-Systeme erwarten:
{
"briefDescription": "...", ← LLM wählt
"caller": {
"name": "...", ← LLM wählt
"phone": "..." ← Dynamische Variable
},
"category": { "name": "Telefon" } ← Konstanter Wert
}
Die Struktur wird unverändert an Ihre API gesendet. Headers und Query Parameters unterstützen keine Objekte — verschachtelte Strukturen gehören in den Request Body.
Schritt 5: Ausführungszeitpunkt wählen
Jede Aktion hat einen Standard-Ausführungszeitpunkt. Sie setzen ihn beim Erstellen im Abschnitt Ausführungszeitpunkt oder nachträglich direkt auf der Aktionskarte in der Aktionsliste (Vorher / Während / Nachher). Pro Agent können Sie den Zeitpunkt zusätzlich überschreiben (Integrationen einrichten).
Der Zeitpunkt bestimmt, wie die Felder befüllt werden — das ist die wichtigste Entscheidung bei eigenen Aktionen:
| Zeitpunkt | Verhalten | Befüllung der Felder |
|---|---|---|
| Vor dem Anruf | Läuft automatisch vor Gesprächsbeginn, das Ergebnis wird als Variable gespeichert | Nur konstante Werte und dynamische Variablen — es gibt noch kein Gespräch |
| Während des Anrufs | Der Agent entscheidet live im Gespräch, wann er die Aktion aufruft | Der Agent kann fehlende Angaben direkt beim Anrufer erfragen, bevor er die Aktion ausführt |
| Nach dem Anruf | Läuft nach Gesprächsende in der Nachverarbeitung | Die Werte werden nachträglich aus dem Gesprächsverlauf ermittelt — Rückfragen sind nicht mehr möglich |
Wichtig: Bei Nach dem Anruf kann nur befüllt werden, was im Gespräch tatsächlich vorkam. Wurde eine Angabe nie besprochen, bleibt das Feld leer. Sorgen Sie im Agenten-Prompt dafür, dass alle benötigten Angaben im Gespräch erhoben werden (Prompt schreiben).
Bei Vor dem Anruf konfigurieren Sie zusätzlich Variable Mappings: Welcher Wert aus der API-Antwort (per JSON-Pfad zum Wert, z. B. data.customer.name) in welche Ziel-Variable geschrieben wird, und das Verhalten Bei Fehler (Variable überspringen, Standardwert verwenden oder Anruf abbrechen). Pro Agent sind maximal 10 solcher Aktionen möglich; sie laufen parallel mit maximal 5 Sekunden Wartezeit. Mehr zu Variablen: Variablen verwenden.
Pflichtfelder absichern
Wenn Ihr Zielsystem bestimmte Felder zwingend erwartet, kombinieren Sie zwei Strategien:
- Erhebung im Gespräch sicherstellen: Weisen Sie den Agenten im Aktions-Prompt und im Agenten-Prompt an, die Pflichtangaben aktiv zu erfragen — bei Ausführung während des Anrufs am besten bevor die Aktion ausgelöst wird.
- Fallback über feste Werte: Befüllen Sie Felder, die nie leer sein dürfen, mit Dynamische Variable (z. B. die Anrufernummer als Referenz) oder Konstanter Wert statt LLM wählt. Diese Werte sind unabhängig vom Gesprächsverlauf immer vorhanden.
Hinweis: Prüfen Sie auch die Gegenseite: Viele Zielsysteme ignorieren unbekannte Werte kommentarlos, statt einen Fehler zu melden. Senden Sie z. B. eine Kategorie, die es im Zielsystem nicht exakt gibt, kommt das Ticket ohne diese Zuordnung an.
Schritt 6: Zuweisen und testen
- Weisen Sie die Integration Ihrem Agenten im Tab Integrationen zu und aktivieren Sie die Aktion (Integrationen einrichten)
- Führen Sie einen Testanruf durch und nennen Sie dabei alle Angaben, die die Aktion benötigt (Agent testen)
- Prüfen Sie das Ergebnis im Zielsystem: Ist der Datensatz angekommen, sind alle Felder korrekt befüllt?
- Prüfen Sie die Anrufdetails: Im Transkript sehen Sie, ob und wann der Agent die Aktion ausgeführt hat; Ergebnisse von Vor-dem-Anruf-Aktionen erscheinen dort als Pre-Call-Tool
Eigene Aktionen lassen sich nicht über den Verbindungstest der Integrationen-Seite prüfen — der Testanruf mit Blick ins Zielsystem ist der verlässliche Weg. Testen Sie bei Aktionen mit Zeitpunkt Nach dem Anruf erst einige Minuten nach Gesprächsende, die Nachverarbeitung braucht einen Moment.
Fehlerbehebung
Der Agent ruft die Aktion nie auf
Prüfen Sie drei Punkte: Ist die Integration dem Agenten zugewiesen und die Aktion dort aktiviert? Steht der Ausführungszeitpunkt auf Während des Anrufs? Beschreibt der Prompt der Aktion klar, in welcher Situation sie verwendet werden soll?
Felder kommen leer im Zielsystem an
Bei Zeitpunkt Nach dem Anruf die häufigste Ursache: Die Angabe kam im Gespräch nicht vor. Hören Sie den Anruf nach bzw. lesen Sie das Transkript — fehlt die Information dort, muss der Agenten-Prompt sie aktiv erfragen. Prüfen Sie außerdem die Feld-Beschreibungen bei LLM wählt und nutzen Sie für kritische Felder dynamische Variablen oder konstante Werte (siehe oben).
Das Zielsystem ignoriert einzelne Felder
Wenn einzelne Werte nicht ankommen, obwohl sie gesendet werden: Prüfen Sie, ob der Wert im Zielsystem exakt so existiert (Schreibweise, Groß-/Kleinschreibung, gültige Auswahlwerte). Viele Systeme verwerfen unbekannte Werte ohne Fehlermeldung.
Die Aktion schlägt fehl oder läuft in einen Timeout
Prüfen Sie Basis-URL und Authentifizierung der Integration sowie den API-Pfad der Aktion. Antwortet Ihre API langsamer als der eingestellte Response Timeout, erhöhen Sie den Wert — bei Ausführung während des Anrufs wartet der Anrufer allerdings so lange mit.
Nächste Schritte
- Integrationen einrichten - Verbindung, Zuweisung und Ausführungszeitpunkt pro Agent
- Variablen verwenden - Dynamische Variablen im Überblick
- Nachverarbeitung - Was nach dem Gespräch passiert
- Agent testen - Testanrufe systematisch durchführen