Aktion des KI‑Agenten: Make HTTP requests

Verfügbarkeit des Plans: Verfügbar in den Advanced-, Enterprise- und ausgewählten Legacy‑Plänen. Tests sind für alle Nutzer verfügbar, aber zum Veröffentlichen brauchst du einen berechtigten Plan.

Die Aktion Make HTTP requests ermöglicht deinem KI‑Agenten, während einer Unterhaltung externe APIs aufzurufen. So kann der KI‑Agent Echtzeitdaten abrufen oder Aktionen in externen Systemen auslösen, basierend auf der Anfrage des Kontakts. Zum Beispiel kann er den Bestellstatus prüfen, Kontoinformationen abrufen oder Datensätze in einem anderen System anlegen. In diesem Artikel lernst du, wie du die HTTP‑Request‑Aktion konfigurierst und sie mit deinem KI‑Agenten testest.

Der KI‑Agent:

1. Analysiert die Nachricht des Kontakts, um festzustellen, ob sie mit der in deinen Aktionsanweisungen definierten Absicht übereinstimmt.

2. Sammelt alle erforderlichen Informationen.

3. Sendet die HTTP‑Anfrage.

4. Interpretiert die API‑Antwort.

5. Antwortet dem Kontakt natürlich.

Füge eine Aktion "Make HTTP requests" hinzu

Schalte die Aktion ein und klicke auf die Schaltfläche "Add action", um mit der Konfiguration deiner HTTP‑Anfrage zu beginnen.

Lege fest, wann die Aktion ausgeführt werden soll

Gib der Aktion im Action name -Feld einen beschreibenden Namen.

Im Feld When and how should this action be performed? Feld, beschreibe:

• Wann der KI‑Agent diese Aktion verwenden soll

• Was sie abruft oder sendet

• Alle Bedingungen oder Ergebnisse, die behandelt werden müssen

Beispiel:

Verwende diese Aktion, um den Bestellstatus eines Kontakts abzurufen, wenn er nach seiner Bestellung fragt. Wenn die API einen 404‑Fehler zurückgibt, informiere den Kontakt, dass die Bestellung nicht gefunden werden konnte.

Der KI‑Agent verwendet diese Beschreibung, um zu entscheiden, wann die Anfrage ausgelöst werden soll.

Informationen, die der KI‑Agent benötigen könnte (optional)

Definiere in diesem Abschnitt die benötigten Eingaben, bevor du deine API aufrufst.

Dabei handelt es sich um strukturierte Variablen, die die KI sammeln muss. Die Anfrage wird nur ausgelöst, nachdem alle erforderlichen Eingaben vorliegen.

Wenn ein Wert:

• Bereits in der Unterhaltung erwähnt → die KI verwendet ihn.

• Fehlt → die KI fragt den Kontakt danach.

Die hier erstellten Variablen können in der API‑Konfiguration verwendet werden. Kontaktvariablen (z. B. $contact.email) sind automatisch verfügbar und müssen nicht hinzugefügt werden.

Feldeinstellungen

API‑Konfiguration

Definiere, wie der KI‑Agent deine API aufrufen soll.

Du kannst konfigurieren:

• Methode

• URL

• Abfrageparameter

• Header

• JSON‑Body (für POST, PUT, PATCH)

Variablen referenzieren

Du kannst Variablen mit $ in URL, Parametern, Headern oder Body einfügen.

Es gibt zwei Typen:

• Kontaktvariablen — bestehende Kontaktfelder

  • $contact.email

• KI‑Agent‑Variablen — Felder, die unter Information the AI Agent may need definiert sind

  • $agent.order_id

Variablen werden beim Ausführen der Anfrage durch echte Werte ersetzt. Wenn eine erforderliche KI‑Agent‑Variable fehlt, fragt die KI danach, bevor der API‑Aufruf ausgelöst wird.

Wie die KI API‑Antworten verarbeitet

Beispiel‑Body:

{
  "order_id": "$agent.order_id",
  "email": "$contact.email"
}

Der KI‑Agent interpretiert automatisch die JSON‑Antwort der API und generiert eine natürliche Antwort.

Beispiel‑API‑Antwort:

{
  "status": "shipped",
  "eta": "2025-12-12"
}

KI‑Antwort: „Gute Nachrichten! Deine Bestellung wurde versandt und wird voraussichtlich am 12. Dezember 2025 ankommen.”

Testen

Du kannst deine HTTP‑Request‑Aktion im Test AI Agent‑Panel testen, bevor du sie veröffentlichst.

So testest du

1. Starte eine Testunterhaltung, die den Bedingungen deiner Aktion entspricht.

   

2. Wenn die Absicht erkannt wird und die erforderlichen Eingaben vorliegen, führt der KI‑Agent die HTTP‑Anfrage aus.

3. Ein Ausführungsereignis erscheint im Test‑Panel:

   

   1. {AI Agent name} führte {Action name} aus

   2. 2xx‑Antworten werden als Erfolg angezeigt

   3. Alle anderen Statuscodes werden als Fehler angezeigt

4. Klicke das Ereignis an, um zu sehen:

   1. Response Tab (Standard) — gesamter API‑Antwortkörper

   2. Request Tab — komplette cURL‑Anfrage

   3. Kopieroption zum Debugging

5. Nach Erhalt der API‑Antwort generiert der KI‑Agent eine Antwort basierend auf den zurückgegebenen Daten.

Wichtige Hinweise

• Ausführungsereignisse erscheinen nur im Test AI Agent‑Panel. Sie erscheinen nicht im Posteingang oder in der Kontaktaktivität.

• Wenn erforderliche Eingaben fehlen, fragt der KI‑Agent danach, bevor er die Anfrage auslöst.

Beste Vorgehensweisen

• Sei präzise in deiner Aktionsbeschreibung. Unklare Anweisungen führen zu unpräzisen Auslösern.

• Definiere erforderliche Eingaben klar. Wenn die KI etwas erfragen muss, mach es deutlich.

• Behandle Fehlerfälle in deinen Anweisungen.

• Teste immer, bevor du veröffentlichst.

• Vermeide die Duplizierung von Logik, die bereits von Workflows gehandhabt wird, es sei denn, es ist absichtlich so gestaltet.

Einschränkungen

• Maximal 10 HTTP‑Request‑Aktionen pro KI‑Agent.

• Maximal pro Aktion:

  • 20 Eingabefelder

  • 50 Parameter

  • 50 Header

• Der KI‑Agent entscheidet, wann die API anhand deiner schriftlichen Beschreibung aufgerufen wird. Schlecht formulierte Anweisungen können unerwartete Auslösungen verursachen.

• Die Verarbeitung der API‑Antworten erfolgt automatisch. Du kannst Antwortfelder nicht manuell zuordnen — die KI interpretiert das JSON kontextbezogen.

• Ausführungsereignisse von HTTP‑Anfragen erscheinen nur im Test AI Agent‑Panel und nicht in der Kontaktaktivität.

• Voice‑KI‑Agenten können die Aktion Make HTTP requests auslösen. Die zurückgegebene API‑Antwort wird jedoch nicht an den Voice‑KI‑Agenten zur Antwortgenerierung übergeben, das heißt Sprachkonversationen können nicht dynamisch auf Basis des API‑Ergebnisses reagieren.