Zum Inhalt

API-Antworten zuordnen und umformen

Mit der Antwortverarbeitung wählst du aus, welche Daten einer API-Antwort der Agent erhält. So kannst du zum Beispiel aus einer umfangreichen Bestellung nur den Namen und den Lieferstatus übernehmen.

Modus auswählen

Modus Zweck
Originalantwort Bereits kleine, brauchbare Antwort
Zugeordnete Antwort JSON-Felder auswählen und benennen
JEXL-Skript Berechnungen, Filter oder eine andere Ausgabestruktur

Pre Processing bietet die entsprechenden Modi Gesamte Antwort, JSON-Felder und Skript. Dort wird die Ausgabe zum Anruferkontext statt zum Tool-Ergebnis.

Felder visuell zuordnen

Lade eine Beispielantwort oder führe einen API-Test mit Testdaten aus, öffne den Mapping-Editor und wähle die benötigten Felder. Vergib verständliche Ausgabenamen.

Für diese synthetische Antwort:

{"customer":{"name":"Beispielperson"},"orders":[{"status":"ready"}]}
Ausgabename Pfad
customer_name $.customer.name
first_order_status $.orders[0].status

Du kannst einzelne Felder, Listeneinträge wie $.orders[0].status oder mehrere Einträge wie $.orders[*].status auswählen. Es werden nicht alle JSONPath-Ausdrücke unterstützt. Prüfe die Auswahl in der Vorschau auch mit fehlenden Feldern und leeren Listen.

JEXL-Skript schreiben

Skripte verwenden JEXL, nicht JavaScript. response enthält das geparste JSON. Bei API-Tools enthalten request.path, request.query und request.body die Anfrageeingaben.

return {
  'customer_name': response.customer.name,
  'first_order_status': response.orders[0].status
};

Dieses Beispiel setzt einen Kunden und mindestens eine Bestellung voraus. Prüfe optionale Strukturen vor dem Zugriff etwa mit data:hasKey(...) und size(...). Die Funktionsreferenz im Editor erklärt Helfer wie data:trim, data:take, data:addMinutes und date:now.

Das Ergebnis muss als JSON darstellbar sein. Verwende die Funktionen aus der Referenz im Editor. Netzwerkaufrufe und externe JavaScript-Bibliotheken stehen in diesen Skripten nicht zur Verfügung.

Ergebnis prüfen

  1. Prüfe die Syntax.
  2. Nutze die Vorschau mit repräsentativem Beispiel-JSON. Sie wiederholt nicht die ursprüngliche API-Anfrage.
  3. Teste fehlende und fehlerhafte Daten.
  4. Führe eine echte Anfrage mit Testdaten aus und vergleiche rohe und verarbeitete Antwort.
  5. Prüfe die Antwort des Agenten in einem Anruf.

Bei RESPONSE_MAPPING_FAILED oder RESPONSE_SCRIPT_FAILED ist die Verarbeitung der Antwort fehlgeschlagen. Prüfe die Feldpfade oder das Skript mit der tatsächlich zurückgegebenen Antwort.