# Outils personnalisés

> Laissez l'IA appeler votre API en pleine conversation

- Page: https://tbit.app/fr/docs/api/custom-tools
- URL de base: `https://rest-api.tbit.app/v1`
- Authentification: en-tête `X-API-Key` avec votre clé dans chaque requête (les exemples la lisent depuis la variable d'environnement `TBIT_API_KEY`)

## Vue d'ensemble

Un outil personnalisé est un endpoint à vous que l'agent peut appeler pendant qu'il parle à un client : consulter un crédit par numéro d'identité, vérifier le stock, ouvrir un ticket. Vous décrivez quand il s'applique et de quels paramètres il a besoin ; l'IA décide quand l'appeler, remplit les paramètres avec ce qu'a dit le client et répond avec ce que votre API a renvoyé. Jusqu'à 15 outils par agent.

## Définition

Chaque outil est une entrée avec ces champs :

|  |
|  |
| `name` | Nom technique avec lequel l'IA l'appelle : lettres, chiffres et tiret bas (consultar_credito). |
| `description` | Quand l'utiliser et ce qu'il renvoie. C'est ce que l'IA lit pour décider ; rédigez-la comme une instruction (« Consulte un crédit par numéro d'identité ; renvoie le solde et les échéances »). |
| `parameters` | Liste de {name, type (string \| number \| boolean \| enum), description, required, enum_values}. L'IA les remplit avec ce qu'a dit le client. |
| `method + endpoint` | GET, POST, PUT ou DELETE et l'URL complète. |
| `auth` | NONE, BEARER (Authorization: Bearer <token>), API_KEY (nom et valeur d'en-tête de votre choix) ou BASIC (utilisateur et mot de passe). |
| `headers` | En-têtes supplémentaires envoyés à chaque appel. |
| `body_template` | Modèle JSON facultatif avec {{param}}. Sans lui, POST/PUT envoient les paramètres comme objet JSON. |
| `response_path` | Chemin à points facultatif (data.results) vers la partie de la réponse que l'IA doit lire. |

## Comment se fait l'appel

GET et DELETE ajoutent les paramètres à l'URL en query string. POST et PUT les envoient en body JSON, ou le body_template une fois rempli. Les en-têtes d'auth et les supplémentaires partent à chaque appel. Répondez 2xx avec du JSON : l'IA reçoit le body (ou la partie de response_path) en texte et s'en sert pour répondre. Un code autre que 2xx arrive à l'IA comme « API returned <status> » et elle dit au client qu'elle n'a pas pu consulter ; il n'y a pas de nouvelle tentative.

## Comment en créer un

- Canvas (newui.tbit.app) : demandez « quels outils personnalisés ai-je ? » → la liste propose « Nouvel outil… » ; chaque ligne ouvre l'outil avec Modifier. Un formulaire demande tout ce qui précède ; les secrets laissés vides lors d'une modification sont conservés.
- MCP (Claude, ChatGPT…) : list_custom_tools pour les lire, manage_custom_tool avec action=create | update | delete. Le changement est proposé et vous le confirmez.
- App de la plateforme : Intégrations → API personnalisée.

## Exemple : créer depuis le 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"
}
```

## Ce que reçoit votre endpoint

Avec l'exemple ci-dessus, quand un client demande où en est son crédit, l'IA appelle :

```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" } }
```

## Bonnes pratiques

- Rédigez la description pour l'IA, pas pour un développeur : quand l'utiliser et ce qu'il renvoie.
- Ne marquez comme obligatoire que ce que l'IA doit demander au client ; pour le reste, prévoyez une valeur par défaut de votre côté.
- Gardez les GET idempotents : l'IA peut appeler le même outil deux fois dans une conversation si la première tentative a échoué.
- Renvoyez un JSON petit et plat. Utilisez response_path si votre API enveloppe les résultats.