API

Tool personalizzati

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

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.