> 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/tools/api-tools.md). # API-tools Een assistent of een Toolbox-element koppelen aan een API. Aan te maken via het tabblad **Tools** van een assistent of element, met **Aanmaken → Eigen tool**. Dit is het meest technische scherm in het platform. Je hebt de documentatie van de API ernaast nodig. ## Wat een API-tool doet Je beschrijft een API-aanroep als een sjabloon met plaatshouders. De assistent bepaalt wanneer de aanroep nodig is, leidt uit het gesprek af wat er in de plaatshouders moet komen, en gebruikt het antwoord om te reageren. Bijvoorbeeld: een assistent die de vraag *"waar is bestelling 10432?"* krijgt, herkent dat hij de tool voor bestellingen nodig heeft, haalt `10432` eruit als bestelnummer, roept jouw API aan en maakt van het antwoord een zin. ## Identiteit | Veld | Wat het doet | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Weergavenaam** | Wat mensen op de toolkaart zien. | | **Weergavebeschrijving** | Wat mensen eronder zien. | | **Zichtbaarheid** | **Privé** houdt de tool binnen deze organisatie. **Directe dochterorganisaties** deelt hem met je dochterorganisaties. | | **Beschrijving voor de LLM** | Wat de assistent leest om te bepalen of hij deze tool gebruikt. | {% hint style="success" %} **Beschrijving voor de LLM** is het veld dat bepaalt of de tool werkt. Schrijf een paar zinnen: wat de tool doet, welke informatie hij nodig heeft, wanneer je hem gebruikt en wanneer niet. *"Zoekt de huidige status en de verwachte leverdatum van een klantbestelling op. Gebruik dit altijd wanneer iemand vraagt naar een bestelling die hij heeft geplaatst. Vereist het bestelnummer."* werkt vele malen beter dan *"Bestelling opzoeken"*. {% endhint %} ## Toolargumenten De argumenten zijn wat de assistent invult. Elk argument dat je opgeeft, wordt een waarde die hij uit het gesprek moet afleiden. Met **Argument toevoegen** maak je er een aan. | Veld | Wat het doet | | ------------------- | --------------------------------------------------------------------------------- | | **Sleutel** | De naam waarnaar je verwijst in de URL, headers of body, bijvoorbeeld `order_id`. | | **Beschrijving** | Wat deze waarde is. De assistent leest dit om te weten wat hij eruit moet halen. | | **Type** | String, Integer, Number, Boolean, Array of Object. | | **Type items** | Voor een Array: wat erin zit. Verplicht. | | **Eigenschappen** | Voor een Object: de velden ervan, op dezelfde manier opgegeven. | | **Standaardwaarde** | Wordt gebruikt als de assistent er geen aanlevert. | | **Verplicht** | Of de aanroep zonder deze waarde niet door kan gaan. | Beschrijvingen van argumenten doen er net zoveel toe als de beschrijving van de tool. `"query"` zegt de assistent niets; `"Het bestelnummer van de klant, zoals het op de bevestigingsmail staat, bijvoorbeeld ORD-10432"` vertelt precies waar hij naar moet zoeken. Houd het aantal argumenten klein en ondubbelzinnig. Elk argument is weer iets waarin de assistent zich kan vergissen. ## API-instellingen | Veld | Wat je invult | | -------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **API URL** | De methode (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) en het endpoint. Verwijs naar argumenten met hun sleutel. | | **Query parameters** | JSON. Optioneel. | | **Headers** | JSON. Optioneel. | | **Body** | JSON. Voor POST, PUT en PATCH. | | **Aantal nieuwe pogingen** | Hoe vaak een mislukte aanroep opnieuw wordt geprobeerd. | | **Time-out (in seconden)** | Hoe lang er wordt gewacht voordat het wordt opgegeven. | Het overzicht **Gebruikte argumenten** laat zien naar welke van je opgegeven argumenten de sjablonen daadwerkelijk verwijzen. Is een argument opgegeven maar ongebruikt, dan ben je vergeten het te plaatsen of heb je het niet nodig. Verwijzen naar een argument dat je niet hebt opgegeven, blokkeert het opslaan. Houd de time-out kort. Er wacht een gebruiker op een antwoord terwijl de aanroep loopt, en een trage tool laat de hele assistent kapot aanvoelen. ## Authenticatie | Optie | Wanneer je die gebruikt | | ---------------------------------- | ---------------------------------------------------------------------------------------- | | **Geen authenticatie** | Alleen bij openbare endpoints. | | **API Key** | Het gebruikelijke geval: een vast token in een header of queryparameter. | | **User bound JWT** | Het token van de ingelogde gebruiker wordt doorgegeven, zodat de API ziet wie er vraagt. | | **OAuth 2.0 (client credentials)** | OAuth tussen systemen onderling. | ### API Key | Veld | Wat je invult | | -------------------------------- | -------------------------------------------------------------------------- | | **Headers key** | De naam van de header, meestal `Authorization`. | | **Key prefix** | Wat er voor de waarde komt, meestal `Bearer` inclusief de spatie erachter. | | **Als queryparameter versturen** | Verstuur de inloggegevens in de querystring in plaats van in een header. | | **Geheime sleutel** | De opgeslagen geheime sleutel met de waarde erin. | ### User bound JWT Stel de **Headers key** en de **Token prefix** in. Er is geen opgeslagen geheime sleutel nodig. Het token van de ingelogde gebruiker wordt doorgegeven. Gebruik dit altijd als de doel-API eigen rechten per gebruiker heeft. Het betekent dat de assistent alleen bij dat kan wat degene die vraagt toch al mag zien, en dat is een veel beter uitgangspunt dan één gedeelde set inloggegevens voor iedereen. ### OAuth 2.0 (client credentials) | Veld | Wat je invult | | ------------------- | --------------------------------------------------------- | | **Token URL** | Waar het token wordt opgehaald. | | **Client ID** | Jouw client identifier. | | **Geheime sleutel** | De opgeslagen geheime sleutel met het client secret erin. | | **Headers key** | De header waarin het token wordt meegestuurd. | {% hint style="warning" %} Inloggegevens horen altijd in een [geheime sleutel](/voor-beheerders/tools/geheime-sleutels.md), nooit ingetypt in een headerveld. Geheimen worden alleen-schrijven opgeslagen en worden na het opslaan nooit meer getoond. {% endhint %} ## Voortgangsbericht Een optionele regel die in de chat wordt getoond terwijl de tool draait, zoals *"Je bestelling wordt opgezocht…"*, in te stellen per taal. De moeite waard voor alles wat langer dan een seconde duurt. Anders ziet de gebruiker niets gebeuren. ## Testen Sla de tool op, zet hem aan voor een testassistent en probeer hem uit in **Voorbeeld**: 1. Vraag iets wat hem zou moeten activeren. Gaat hij af? 2. Vraag iets wat hem niet zou moeten activeren. Blijft hij weg? 3. Vraag iets dubbelzinnigs. Vraagt hij om de ontbrekende informatie in plaats van te gokken? 4. Probeer een waarde die zal mislukken: een bestelnummer dat niet bestaat. Gaat de assistent netjes met de fout om? Gaat de tool nooit af, dan is de **Beschrijving voor de LLM** vrijwel altijd de reden. ## Bewerken en verwijderen Het menu op de toolkaart biedt **Bewerken** en **Verwijderen**. Je kunt alleen tools bewerken die je eigen organisatie heeft gemaakt. Tools die vanuit een moederorganisatie worden gedeeld en platformtools zijn alleen-lezen.