Support-Agenten

Viele Fragen, die Familien an Admins richten, lassen sich im Admin-Panel beantworten: Hat mein Kind einen Platz bekommen? Ist meine Zahlung angekommen? Warum habe ich keine E-Mail erhalten? Dieser Leitfaden zeigt, wie ein KI-Agent oder ein Helpdesk-Tool dieselben Antworten über die API nachschlägt, für die Familie, die fragt, und für niemanden sonst.

Bevor Sie einen KI-Agenten anbinden

Ein Agent, der auf einem Sprachmodell beruht, sendet die Daten, die er liest, an den Anbieter des Modells. Verantwortlich für diese Daten ist die Organisation, die fepli betreibt. Bevor der Agent Daten liest, klärt die Organisation diese Punkte mit der oder dem Datenschutzbeauftragten:

• einen Auftragsverarbeitungsvertrag mit dem Anbieter des Modells und mit dem Anbieter des Helpdesk-Tools,
• ob einer der beiden Anbieter die Daten außerhalb der EU oder des EWR verarbeitet und auf welcher Grundlage,
• eine Datenschutz-Folgenabschätzung, weil der Agent Daten von Kindern automatisiert verarbeitet,
• wie Familien erfahren, dass ein Agent ihre Fragen beantwortet und welche Daten er liest,
• eine Person, die entscheidet, bevor sich etwas an einer Anmeldung ändert. Der Agent antwortet und bereitet einen Fall vor. Er entscheidet nicht.

Wissen, wer fragt

Der Agent handelt nur für eine Person, deren Identität feststeht, und nur in ihrem eigenen Konto:

• Die Identität stammt aus Ihrem Kanal, nicht aus der Frage. Entweder ist die Familie in diesem Kanal angemeldet (eine authentifizierte Sitzung), oder sie schreibt von einer Absenderadresse, die Ihr Helpdesk verifiziert und an ihr fepli-Konto gebunden hat.
• Ihre Integration macht aus dieser Identität die uuid des Kontos, bevor der Agent startet, und behält sie bei der Sitzung oder dem Helpdesk-Kontakt. Bei einer verifizierten Absenderadresse schlägt sie das Konto einmal mit GET /accounts?email=… nach, außerhalb des Agenten.
• Jedes Tool begrenzt seinen Aufruf auf diese uuid. Kein Tool nimmt ein Konto, einen Namen oder eine E-Mail-Adresse vom Agenten entgegen. Eine Adresse oder ein Name, die in einer Frage stehen, werden nie nachgeschlagen. Fragen zu anderen Familien gehen an die Admins.

Schreibgeschützten Service-Account einrichten

Legen Sie für den Agenten einen Service-Account mit der Zugriffsstufe Nur lesen an. Ein Token, das nur liest, kann nichts ändern. Es kann aber alles lesen, was seine Rollen erlauben, und dazu gehören die Daten von Familien und Kindern. Geben Sie ihm nur die Rollen, die seine Tools brauchen (siehe die Tools):

bin/console ferienpass:api:service-account "Support-Agent" --tenant=elmsbrueck \
  --role=ROLE_ADMIN --role=ROLE_PAYMENTS_ADMIN --valid-until="+90 days" \
  --description="Answers verified families' questions in the helpdesk"

Ohne --role vergibt der Befehl nur Admin. Fügen Sie Zahlungen wie oben nur hinzu, wenn der Agent Fragen zu Zahlungen beantwortet. Die Rolle gilt nur zusammen mit Admin.

Geben Sie jedem Token ein Ablaufdatum und erneuern Sie es, bevor es abläuft: Erstellen Sie auf der Seite des Service-Accounts ein neues Token, stellen Sie den Agenten darauf um und widerrufen Sie dann das alte. Widerrufen Sie ein Token sofort, wenn es möglicherweise offengelegt wurde.

Lassen Sie Ihre Integration beim Start GET /me aufrufen. Die Antwort bestätigt "access": "read" und die Rollen. In Installationen mit mehreren Mandanten nennt sie außerdem, für welchen Mandanten das Token gilt.

Fragen und die Aufrufe, die sie beantworten

In den folgenden Aufrufen ist {account} die uuid aus der verifizierten Sitzung, zum Beispiel die von Anna Müller:

curl -G https://example.fepli.eu/api/attendances \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -d account=0191c7b2-4d5e-7f60-8a1b-2c3d4e5f6a05 \
  -d edition=herbstferien-2026

Tools für den Agenten auswählen

Ein Agent arbeitet besser mit einer Handvoll gut beschriebener Tools als mit einem allgemeinen HTTP-Client. Jedes Tool setzt {account} selbst ein. Der Agent wählt nur, welches Tool er aufruft.

Geben Sie dem Service-Account die Rollen der Tools, die Sie verwenden, und keine weiteren. Lassen Sie jedes Tool nur die Felder weitergeben, die die Antwort braucht, und nicht den ganzen Datensatz. Ein Konto enthält zum Beispiel auch die Adresse und die Telefonnummern der Familie.

Geben Sie die detail-Meldungen der API an den Agenten zurück, wenn ein Aufruf fehlschlägt. Sie sind verständlich geschrieben und nennen meist, was Sie stattdessen versuchen können.

Den Fall übergeben

Wenn eine Familie etwas geändert haben möchte, zum Beispiel eine Anmeldung abmelden, sammelt der Agent, was die Admins brauchen, und eine Person entscheidet. Der Agent kann seine Zusammenfassung als interne Notiz am Konto hinterlassen:

curl -X POST "https://example.fepli.eu/api/accounts/0191c7b2-4d5e-7f60-8a1b-2c3d4e5f6a05/comments" \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "The family asks to withdraw Lena from the bike tour on Wednesday: they are away on a family trip that week. Nothing changed; please decide."}'

Notizen, die über die API geschrieben werden, sind intern: Nur Admins sehen sie, sie zeigen den Namen des Service-Accounts als Autor, und sie benachrichtigen die Admins des Mandanten. Um eine Notiz zu schreiben, brauchen Sie ein Token mit Schreibzugriff, und ein solches Token kann alles, was seine Rollen erlauben. Geben Sie dem Notiz-Tool einen eigenen Service-Account mit Lesen und schreiben und nur Admin. Verwenden Sie sein Token in keinem anderen Tool.

Die Person, die entscheidet, führt die Entscheidung im Admin-Panel aus. Wenn Ihr Helpdesk-Tool das für sie übernimmt, sobald sie bestätigt, verwendet es einen eigenen Service-Account, niemals den des Agenten:

curl -X POST "https://example.fepli.eu/api/attendances/0192d0e8-3a4b-7c5d-9e6f-7a8b9c0d1e07/transition" \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transition": "withdraw", "notify": true}'

Übergänge schicken der Familie nur dann eine E-Mail, wenn Sie "notify": true übergeben.

Personenbezogene Daten

Der Agent sieht Namen, Adressen und Kontaktdaten von Familien und Kindern. Behandeln Sie seine Protokolle und Transkripte wie das Admin-Panel: Bewahren Sie sie nur dort auf, wo Ihre Auftragsverarbeitungsverträge sie abdecken, lassen Sie nur Admins sie lesen, und löschen Sie sie, wenn der Fall abgeschlossen ist.