# Tool personalizzati

> Lascia che l'IA chiami la tua API nel mezzo di una conversazione

- Pagina: https://tbit.app/it/docs/api/custom-tools
- URL base: `https://rest-api.tbit.app/v1`
- Autenticazione: header `X-API-Key` con la tua chiave in ogni richiesta (gli esempi la leggono dalla variabile d'ambiente `TBIT_API_KEY`)

## Panoramica

Un tool personalizzato è un tuo endpoint che l'agente può chiamare mentre parla con un cliente: consultare un credito per numero di documento, controllare lo stock, aprire un ticket. Tu descrivi quando si applica e quali parametri servono; l'IA decide quando chiamarlo, compila i parametri con quello che ha detto il cliente e risponde con quello che ha restituito la tua API. Fino a 15 tool per agente.

## Definizione

Ogni tool è una voce con questi campi:

|  |
|  |
| `name` | Nome tecnico con cui l'IA lo chiama: lettere, numeri e trattino basso (consultar_credito). |
| `description` | Quando usarlo e cosa restituisce. È quello che l'IA legge per decidere; scrivilo come un'istruzione («Consulta un credito per numero di documento; restituisce saldo e rate»). |
| `parameters` | Lista di {name, type (string \| number \| boolean \| enum), description, required, enum_values}. L'IA li compila con quello che ha detto il cliente. |
| `method + endpoint` | GET, POST, PUT o DELETE e l'URL completo. |
| `auth` | NONE, BEARER (Authorization: Bearer <token>), API_KEY (nome e valore dell'header che scegli tu) o BASIC (utente e password). |
| `headers` | Header extra che vanno in ogni chiamata. |
| `body_template` | Template JSON facoltativo con {{param}}. Senza, POST/PUT inviano i parametri come oggetto JSON. |
| `response_path` | Percorso facoltativo con punti (data.results) verso la parte della risposta che l'IA deve leggere. |

## Come viene fatta la chiamata

GET e DELETE aggiungono i parametri all'URL come query string. POST e PUT li inviano come body JSON, oppure il body_template già compilato. Gli header di auth e quelli extra vanno in ogni chiamata. Rispondi 2xx con JSON: l'IA riceve il body (o la parte indicata da response_path) come testo e lo usa per rispondere. Un codice diverso da 2xx arriva all'IA come «API returned <status>» e lei dice al cliente che non è riuscita a consultare; non ci sono nuovi tentativi automatici.

## Come crearne uno

- Canvas (newui.tbit.app): chiedi «quali tool personalizzati ho?» → l'elenco ha «Nuovo tool…»; ogni riga apre il tool con Modifica. Un modulo chiede tutto quanto sopra; i segreti che lasci vuoti quando modifichi vengono conservati.
- MCP (Claude, ChatGPT…): list_custom_tools per leggerli, manage_custom_tool con action=create | update | delete. La modifica viene proposta e tu la confermi.
- App della piattaforma: Integrazioni → API personalizzata.

## Esempio: creare dall'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"
}
```

## Cosa riceve il tuo endpoint

Con l'esempio sopra, quando un cliente chiede del suo credito l'IA chiama:

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

## Buone pratiche

- Scrivi la descrizione per l'IA, non per uno sviluppatore: quando usarlo e cosa restituisce.
- Segna come obbligatorio solo quello che l'IA deve chiedere al cliente; per il resto, metti un valore predefinito dalla tua parte.
- Mantieni i GET idempotenti: l'IA può chiamare lo stesso tool due volte in una conversazione se il primo tentativo è fallito.
- Restituisci un JSON piccolo e piatto. Usa response_path se la tua API incapsula i risultati.