> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/voor-beheerders/assistenten/triggers.md).

# Triggers

Een assistent zelfstandig aan het werk laten gaan, zonder dat iemand een chat opent. In te stellen op het tabblad **Triggers** van een assistent.

## Waar een trigger voor is

Een assistent wacht normaal op een vraag. Met een trigger begint hij uit zichzelf: op een vast moment, als een ander systeem hem iets stuurt, of als er een e-mail naar hem wordt doorgestuurd. De assistent voert dan de opdracht uit die je hebt geschreven, en het resultaat wordt bewaard zodat je het kunt nalopen.

Zo'n zelfstandige uitvoering heet een **run**. [Runs en de Cockpit](https://docs.artific.nl/voor-beheerders/assistenten/runs.md) legt uit hoe je runs volgt, controleert en beheert.

Triggers passen bij werk dat terugkomt, of dat begint met een gebeurtenis ergens anders:

* een wekelijkse marktbriefing,
* het verwerken van facturen die finance doorstuurt,
* opvolging zodra er in je CRM een campagne start.

## De drie soorten triggers

| Trigger       | Start als                                                                                                          | Typisch gebruik                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| **Planning**  | Een vast moment: dagelijks, wekelijks, maandelijks, eenmalig of volgens een eigen schema.                          | Terugkerende rapportages en controles.                                     |
| **Webhook**   | Een ander systeem het eigen adres van de trigger aanroept. Wat het meestuurt, krijgt de assistent mee als context. | Reageren op gebeurtenissen in een CRM, een formulier of je eigen software. |
| **Mail-hook** | Er een e-mail binnenkomt op het eigen adres van de trigger.                                                        | Mail afhandelen die een team doorstuurt, zoals facturen.                   |

## Een trigger toevoegen

1. Open de beheeromgeving van de assistent en kies het tabblad **Triggers**.
2. Kies **Trigger toevoegen** en daarna **Planning**, **Webhook** of **Mail-hook**.
3. Geef hem een **Naam** die zegt wat hij doet, zoals *Wekelijkse marktbriefing*.
4. Schrijf de **Opdracht voor** de assistent: wat hij moet doen als de trigger afgaat. Schrijf het zoals je het een collega zou vragen.
5. Stel de limieten in, en als je wilt de criteria, menselijke goedkeuring en notificaties die hieronder staan.
6. Kies **Trigger aanmaken**.

Elke trigger in de lijst heeft een eigen schakelaar, zodat je hem kunt stilzetten zonder hem te verwijderen. De lijst laat bij een planning ook zien wanneer hij de volgende keer draait.

## Planning

Een planning kent drie vormen:

| Vorm         | Wat je instelt                                                                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Herhalen** | Dagelijks, wekelijks of maandelijks, op een vast tijdstip. Maandelijks kan op een datum, of op een weekdag zoals de eerste maandag van de maand. |
| **Eenmalig** | Eén datum en tijd. Daarna schakelt de trigger zichzelf uit.                                                                                      |
| **Cron**     | Onder **Geavanceerd**: een cron-expressie voor schema's die de andere vormen niet aankunnen.                                                     |

Tijden staan in een tijdzone, die je per trigger kunt **Wijzigen**. Staat een maandelijkse planning op een dag die een kortere maand niet heeft, dan draait hij op de laatste dag van die maand.

Met **Gemiste run alsnog uitvoeren** wordt een geplande run die niet kon starten later alsnog uitgevoerd, in plaats van overgeslagen.

Een cron-expressie heeft vijf velden: minuut, uur, dag van de maand, maand en dag van de week. Tussen twee runs moet minstens vijf minuten zitten.

## Webhook

Als je de trigger aanmaakt, krijgt hij een eigen **Webhook-URL**. Geef dat adres aan het externe systeem. Zodra daar iets binnenkomt, start er een run en gaat de inhoud als context mee naar de assistent.

Dit deel is technisch. Ben jij niet degene die het externe systeem koppelt, geef het dan door aan wie dat wel doet.

### Authenticatie

Elke aanroep moet aantonen dat hij van het juiste systeem komt. Kies onder **Authenticatie** een van twee manieren:

| Manier                           | Hoe het werkt                                                                                                                                                                           |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Signature (HMAC)**             | De aanbevolen manier. Het externe systeem ondertekent elke aanroep met een secret, zodat het platform zowel de afzender controleert als dat de inhoud niet is gewijzigd.                |
| **Gedeeld secret in een header** | Het externe systeem stuurt het secret zelf mee met elke aanroep. Zwakker: het bewijst niet dat de inhoud onderweg niet is gewijzigd. Alleen voor systemen die niet kunnen ondertekenen. |

Het secret is een van de [geheime sleutels](https://docs.artific.nl/voor-beheerders/tools/geheime-sleutels.md) van je organisatie. Kies een bestaande onder **Signing secret**, of kies **Nieuw secret genereren**. Aanroepen zonder geldige ondertekening worden geweigerd, net als ondertekende aanroepen die ouder zijn dan vijf minuten. Het triggerscherm laat precies zien wat het externe systeem moet meesturen.

Met een optionele `Idempotency-Key`-header geeft een herhaalde aanroep binnen 24 uur de eerste run terug in plaats van een nieuwe te starten. Gebruik dat als het externe systeem dezelfde gebeurtenis twee keer kan sturen.

### Variabelen

In plaats van het hele binnenkomende bericht door te geven, kun je de velden eruit halen die je nodig hebt.

| Veld          | Wat het doet                                                                                 |
| ------------- | -------------------------------------------------------------------------------------------- |
| **Naam**      | Hoe je de waarde in de opdracht noemt, gebruikt als `{{naam}}`.                              |
| **Veld**      | Waar de waarde in de binnenkomende gegevens staat, als JSON-pointer zoals `/factuur/nummer`. |
| **Verplicht** | Of een aanroep zonder deze waarde wordt geweigerd.                                           |

Een waarde gaat altijd als geciteerde gegevens de opdracht in, nooit als opdracht.

{% hint style="warning" %}
Een variabele met een leeg veld geeft de hele binnenkomende inhoud door. Alles wat de afzender stuurt, komt dan in de opdracht van de assistent terecht, dus wie het adres kan aanroepen, schrijft er een deel van. Haal waar je kunt alleen de velden eruit die je nodig hebt.
{% endhint %}

## Mail-hook

Als je de trigger aanmaakt, krijgt hij een eigen **Doorstuuradres**. Stuur een e-mail door naar dat adres en de assistent start een run met de mail als invoer. Bijlagen gaan mee als bestanden.

In de opdracht zet je met `{{subject}}` en `{{body_text}}` het onderwerp en de tekst van de e-mail neer.

**Toegestane afzenders** bepaalt wie een run mag starten, één per regel:

* een volledig adres, zoals `finance@voorbeeld.nl`,
* of `@voorbeeld.nl` voor iedereen op dat domein.

Mail van anderen start niets, en mail die niet door de afzendercontroles komt die bewijzen dat een e-mail echt van dat domein komt ook niet. Automatische antwoorden en bounces worden genegeerd. De trigger laat zien hoeveel e-mails zijn genegeerd, zodat je merkt wanneer een collega doorstuurt vanaf een adres dat niet op de lijst staat.

## Opdracht, criteria en limieten

### Opdracht

De opdracht is de taak voor deze trigger, bovenop de eigen [instructies](https://docs.artific.nl/voor-beheerders/assistenten/instellingen.md) van de assistent. Zeg wat hij moet doen, welke bronnen hij gebruikt, hoe het resultaat eruit moet zien en waar het naartoe moet. Vage opdrachten geven vage runs.

### Criteria voor een geslaagde run

Optioneel, en de moeite waard om in te vullen. Als een run klaar is, toetst de assistent het resultaat aan deze criteria. Een run die er niet aan voldoet, mislukt.

> *Het bedrag klopt met de bestelling. De klant wordt bij naam aangesproken.*

Met criteria wordt "de run is klaar" ook "de run deed wat hij moest doen". Ze zorgen er ook voor dat een mislukte run makkelijk opvalt in de [Cockpit](https://docs.artific.nl/voor-beheerders/assistenten/runs.md).

### Limieten

| Instelling                         | Wat het doet                                                                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Tijdslimiet per run (minuten)**  | Een run die langer werkt, stopt als mislukt.                                                                                          |
| **Kostenlimiet per run ($)**       | Een run die meer kost, stopt als mislukt.                                                                                             |
| **Maximaal aantal acties per run** | Een actie is een stap waarin de assistent een tool gebruikt. Bij dit aantal stopt de run, rondt af met wat er is en telt als mislukt. |

Elke limiet heeft een bovengrens. Samen zorgen ze ervoor dat een run nooit onbeperkt kan doorlopen. [Budgetten](https://docs.artific.nl/voor-beheerders/organisatie/budgetten.md) leggen daar nog een maandplafond bovenop.

## Menselijke goedkeuring

**Menselijke goedkeuring** bepaalt wanneer de assistent eerst een mens erbij betrekt.

Zet het aan en beschrijf de gevallen in gewone taal bij **Wanneer moet de assistent je erbij betrekken?**:

> *Vraag eerst toestemming voordat je e-mail naar een klant stuurt. Als het ordernummer ontbreekt, vraag me erom. Interne e-mail naar @voorbeeld.nl mag zonder vragen verstuurd worden.*

Vóór elke actie, en wanneer er informatie ontbreekt, bepaalt de assistent aan de hand van deze instructie of hij om goedkeuring vraagt of een vraag stelt.

| Situatie                                    | Wat er gebeurt                                                                                                                                                                         |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Instructie leeg gelaten                     | De assistent vraagt om goedkeuring vóór elke actie die iets buiten het gesprek verandert: versturen, aanmaken, bijwerken of verwijderen. Ontbreekt er informatie, dan vraagt hij erom. |
| Zoeken in de kennisbank                     | Vraagt nooit om goedkeuring.                                                                                                                                                           |
| Een connector waarvoor iemand moet inloggen | Vraagt dat altijd, wat de instructie ook zegt.                                                                                                                                         |
| Sub-agents                                  | Vragen nooit. Hun acties vallen niet onder deze instructie.                                                                                                                            |
| **Menselijke goedkeuring** uit              | Runs wachten nooit op een mens.                                                                                                                                                        |

Goedkeuren en antwoorden gebeurt altijd in het platform. Hoe dat eruitziet voor wie het gevraagd wordt, staat in [Als een assistent je nodig heeft](https://docs.artific.nl/voor-iedereen/assistenten/wacht-op-jou.md).

{% hint style="warning" %}
De assistent volgt de goedkeuringsinstructie zo goed als hij die begrijpt. Beschrijf de gevallen duidelijk en stem ze af met wie verantwoordelijk is voor het proces, zeker als de assistent e-mail verstuurt of gegevens in andere systemen aanpast.
{% endhint %}

## Notificaties

Kies onder **Notificaties · e-mail per status** wie per status een e-mail krijgt. Dat kunnen gebruikers of gebruikersgroepen zijn.

| Status               | Verstuurd als                      |
| -------------------- | ---------------------------------- |
| **Gestart**          | De run is gestart.                 |
| **Afgerond**         | Het resultaat is afgeleverd.       |
| **Vereist aandacht** | Er is goedkeuring of invoer nodig. |
| **Mislukt**          | De run is gestopt met een fout.    |

Een status zonder ontvangers stuurt geen e-mail. Elke pauze voor goedkeuring of invoer stuurt één e-mail, en met **Herinnering** stel je in na hoeveel uur er één herinnering uitgaat als niemand heeft gereageerd.

Onder **Webhooks** kun je de gebeurtenissen van deze trigger ook naar andere systemen sturen. Die webhooks stel je in bij [Meldingskanalen](https://docs.artific.nl/voor-beheerders/organisatie/meldingskanalen.md).

## Werkt als

Runs werken als het eigen triggeraccount van de assistent, dat automatisch wordt aangemaakt en bijgehouden. Onder **Geavanceerd** kun je in plaats daarvan een ander [serviceaccount](https://docs.artific.nl/voor-beheerders/toegang/service-accounts.md) kiezen, maar doe dat alleen als runs de rechten daarvan nodig hebben.

Is het gekozen serviceaccount uitgeschakeld of verwijderd, dan mislukken runs tot je het inschakelt of een ander kiest.

## Nu uitvoeren

**Nu uitvoeren** start de trigger meteen, zonder op het moment te wachten. Vul de waarden in die de opdracht gebruikt, en de run start alsof de trigger was afgegaan. Gebruik het om een nieuwe opdracht te testen voordat je op de planning vertrouwt.

Een trigger voert één run tegelijk uit. Zolang er nog een run loopt, start er geen nieuwe.

## Gekoppelde accounts

Gebruikt een assistent een connector die met het eigen account van een persoon werkt, dan werkt een run via het connector-account van degene die het heeft gekoppeld. **Gekoppelde accounts** bij de trigger laat zien wiens account dat is en sinds wanneer. Met **Intrekken** stopt dat voor volgende runs.

## Een trigger verwijderen

**Verwijderen** stopt de trigger en haalt hem weg. Runs die hij al startte, houden hun geschiedenis.

## Een trigger goed inrichten

* **Begin met menselijke goedkeuring aan.** Laat het los zodra je een aantal runs goed hebt zien gaan.
* **Test met Nu uitvoeren** voordat je de planning aanzet.
* **Schrijf criteria.** Zonder criteria ziet een run die klaar is maar het verkeerde deed er nog steeds geslaagd uit.
* **Begin met krappe limieten** en verruim ze als runs meer ruimte nodig hebben.
* **Loop de eerste runs stap voor stap na** in de [Cockpit](https://docs.artific.nl/voor-beheerders/assistenten/runs.md) voordat je de trigger aan zichzelf overlaat.
