Support agents

Many questions families ask admins can be answered from the admin: did my child get a place, did you get my payment, why didn't I get an e-mail? This guide shows how to let an AI agent or a helpdesk tool look up the same answers through the API, for the family that asks and for nobody else.

Before you connect an AI agent

An agent built on a language model sends the data it reads to the model's provider. The organisation that runs fepli is responsible for that data. Before the agent reads any of it, the organisation settles these points with its data protection officer:

• a data processing agreement with the provider of the model, and with the provider of the helpdesk tool,
• whether either provider processes the data outside the EU or the EEA, and on what basis,
• a data protection impact assessment, because the agent processes children's data automatically,
• how families learn that an agent answers their questions, and which data it reads,
• a person who decides before anything about an attendance changes. The agent answers and prepares a case; it doesn't decide.

Know who is asking

The agent acts only for a requester whose identity is established, and only on that requester's own account:

• The identity comes from your channel, not from the question. Either the family is signed in to it (an authenticated session), or they write from a sender address your helpdesk has verified and bound to their fepli account.
• Your integration turns that identity into the account's uuid before the agent starts, and keeps it with the session or the helpdesk contact. For a verified sender, it looks the account up once with GET /accounts?email=…, outside the agent.
• Every tool scopes its call to that uuid. No tool takes an account, a name or an e-mail address from the agent. An address or a name typed into a question is never looked up, and questions about other families go to the admins.

Set up a read-only service account

Create a service account for the agent with the access level Nur lesen. A read-only token can't change anything, but it can read everything its roles allow, and that includes the data of families and children. Give it only the roles its tools need (see the 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"

Without --role, the command grants Admin only. Add Zahlungen, as above, only if the agent answers questions about payments; it counts only next to Admin.

Give every token an expiry date, and rotate it before it expires: create a new token on the service account's page, switch the agent over, then revoke the old one. Revoke a token at once if it may have leaked.

Have your integration call GET /me when it starts. It confirms "access": "read" and the roles, and, on installations with several tenants, tells you which tenant the token works for.

Questions and the calls that answer them

In the calls below, {account} is the uuid from the verified session, for example Anna Müller's:

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

Give the agent tools, not the whole API

An agent works best with a handful of well-described tools rather than a generic HTTP client. Each tool fills in {account} itself; the agent only chooses which tool to call.

Give the service account the roles of the tools you use, and no others. Let each tool pass on only the fields the answer needs, not the whole record: an account, for example, also holds the family's address and phone numbers.

Pass the API's detail messages back to the agent when a call fails. They are written to be understood and usually say what to try instead.

Hand the case over

When a family wants something changed, for example an attendance withdrawn, the agent collects what the admins need, and a person decides. The agent can leave its summary as an internal note on the account:

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."}'

Notes written through the API are internal: only admins see them, they show the service account's name as author, and they notify the tenant's admins. Writing a note needs a token with write access, and such a token can do everything its roles allow. Give the note tool a service account of its own, with Lesen und schreiben and only Admin, and keep its token out of every other tool.

The person who decides carries the decision out in the admin. If your helpdesk tool does it for them once they confirm, it uses a service account of its own, never the agent's:

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}'

Transitions only e-mail the family when you pass "notify": true.

Personal data

The agent sees names, addresses and contact details of families and children. Treat its logs and transcripts as you would treat the admin: keep them only where your data processing agreements cover them, let only admins read them, and delete them when the case is closed.