# Aangepaste tools

> Laat de AI midden in een gesprek je API aanroepen

- Pagina: https://tbit.app/nl/docs/api/custom-tools
- Basis-URL: `https://rest-api.tbit.app/v1`
- Authenticatie: header `X-API-Key` met je sleutel bij elk verzoek (de voorbeelden lezen hem uit de omgevingsvariabele `TBIT_API_KEY`)

## 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.