API

Aangepaste tools

Laat de AI midden in een gesprek je API aanroepen

Overzicht

Een aangepaste tool is een endpoint van jou dat de agent kan aanroepen terwijl hij met een klant praat: een krediet opzoeken op documentnummer, de voorraad checken, een ticket openen. Jij beschrijft wanneer de tool van toepassing is en welke parameters nodig zijn; de AI beslist wanneer hij hem aanroept, vult de parameters in met wat de klant zei en antwoordt met wat je API teruggaf. Tot 15 tools per agent.

Definitie

Elke tool is een item met deze velden:

`name`	Technische naam waarmee de AI de tool aanroept: letters, cijfers en underscore (consultar_credito).
`description`	Wanneer je hem gebruikt en wat hij teruggeeft. Dit leest de AI om te beslissen; schrijf het als een instructie («Zoekt een krediet op documentnummer op; geeft saldo en termijnen terug»).
`parameters`	Lijst van {name, type (string \| number \| boolean \| enum), description, required, enum_values}. De AI vult ze in met wat de klant zei.
`method + endpoint`	GET, POST, PUT of DELETE en de volledige URL.
`auth`	NONE, BEARER (Authorization: Bearer <token>), API_KEY (naam en waarde van de header die jij kiest) of BASIC (gebruikersnaam en wachtwoord).
`headers`	Extra headers die bij elke aanroep worden meegestuurd.
`body_template`	Optionele JSON-template met {{param}}. Zonder template sturen POST/PUT de parameters als JSON-object.
`response_path`	Optioneel pad met punten (data.results) naar het deel van de response dat de AI moet lezen.

Zo verloopt de aanroep

GET en DELETE zetten de parameters als query string in de URL. POST en PUT sturen ze als JSON-body, of de ingevulde body_template. De auth-headers en de extra headers gaan bij elke aanroep mee. Antwoord met 2xx en JSON: de AI krijgt de body (of het deel uit response_path) als tekst en gebruikt die om te antwoorden. Een andere code dan 2xx komt bij de AI binnen als «API returned <status>» en die vertelt de klant dat het opzoeken niet lukte; er zijn geen automatische nieuwe pogingen.

Zo maak je er een

Canvas (newui.tbit.app): vraag «welke aangepaste tools heb ik?» → de lijst heeft «Nieuwe tool…»; elke rij opent de tool met Bewerken. Een formulier vraagt om alles hierboven; geheimen die je bij het bewerken leeg laat, blijven bewaard.
MCP (Claude, ChatGPT…): list_custom_tools om ze te lezen, manage_custom_tool met action=create | update | delete. De wijziging wordt voorgesteld en jij bevestigt hem.
App van het platform: Integraties → Aangepaste API.

Voorbeeld: aanmaken vanuit de MCP

json

manage_custom_tool
{
  "action": "create",
  "name": "consultar_credito",
  "description": "Consulta el estado de un crédito por número de cédula; devuelve saldo, cuotas pendientes y próxima fecha de pago.",
  "method": "GET",
  "endpoint": "https://api.tunegocio.com/v1/creditos",
  "parameters": [
    { "name": "cedula", "type": "string", "description": "Cédula del cliente, solo dígitos", "required": true }
  ],
  "auth_type": "BEARER",
  "auth_token": "<tu token>",
  "response_path": "data"
}

Wat je endpoint ontvangt

Met het voorbeeld hierboven roept de AI, als een klant naar zijn krediet vraagt, dit aan:

http

GET https://api.tunegocio.com/v1/creditos?cedula=1032456789
Authorization: Bearer <tu token>
Accept: application/json

→ 200 { "data": { "saldo": 1250000, "cuotas_pendientes": 3, "proximo_pago": "2026-10-05" } }

Best practices

Schrijf de beschrijving voor de AI, niet voor een developer: wanneer de tool te gebruiken en wat hij teruggeeft.
Maak alleen verplicht wat de AI aan de klant moet vragen; geef de rest aan jouw kant een standaardwaarde.
Houd GET-aanroepen idempotent: de AI kan dezelfde tool twee keer in een gesprek aanroepen als de eerste poging mislukte.
Geef kleine, platte JSON terug. Gebruik response_path als je API de resultaten verpakt.