Integrazioni

Collega i tuoi agenti IA a sistemi esterni. Aggiungi un server MCP, importa una specifica OpenAPI o configura a mano gli endpoint HTTP, poi salva le credenziali in modo sicuro nel gestore dei segreti e testa tutto dalla dashboard.

Le integrazioni estendono le capacità del tuo agente oltre le risposte basate sulla base di conoscenza. Tramite una connessione, il tuo agente può chiamare API esterne durante una conversazione: consultare dati in tempo reale, verificare le giacenze, recuperare lo stato di un ordine o avviare flussi di lavoro in altri sistemi.

Gestisci le integrazioni in Integrazioni nella barra laterale. La pagina ha due schede:

• Strumenti: le connessioni che i tuoi agenti possono chiamare; ognuna fornisce uno o più strumenti.
• Segreti: chiavi API e credenziali cifrate, richiamate dalle connessioni come $secret:key.

Connessioni e segreti si definiscono una volta per organizzazione e sono condivisi da tutti gli agenti. Ogni agente sceglie poi quali connessioni usa (vedi Collegare gli strumenti agli agenti).

Chi può fare cosa

Chi ha il ruolo Membro non vede la voce Integrazioni nella barra laterale e, se apre direttamente l'URL, viene reindirizzato alla Chat. Chi ha il ruolo Builder può vedere tutto e collegare gli strumenti esistenti agli agenti, ma per creare o modificare connessioni e segreti serve il ruolo Admin o Proprietario.

Strumenti integrati

Oltre alle connessioni, gli agenti dispongono di una serie di strumenti integrati. La maggior parte si configura nell'editor dell'agente (scheda Configura), non nella pagina Integrazioni:

Connessioni

Una connessione è un sistema esterno che la tua organizzazione ha collegato. Ogni connessione fornisce uno o più strumenti che un agente può chiamare quando ritiene che l'azione sia adatta alla conversazione.

L'URL e le credenziali si configurano una volta sola, sulla connessione. Tutto ciò che sta sotto le eredita, e ogni agente attiva poi le connessioni che gli servono, con tutti i loro strumenti importati.

Esistono due tipi, che scegli nel primo passaggio della procedura di aggiunta:

Un terzo riquadro, Managed, è visibile solo allo staff della piattaforma botts.ai. Vedi Strumenti managed.

Aggiungere una connessione

Clicca su Nuovo Strumento nella scheda Strumenti. L'aggiunta è una procedura guidata in tre passaggi, con un indicatore Origine → Connessione → Importa su cui puoi cliccare per spostarti avanti e indietro tra i passaggi che hai già visitato.

Quando modifichi una connessione esistente parti dal passaggio 2. L'origine di una connessione non si può cambiare dopo la creazione.

Il catalogo

Il passaggio 1 mostra un catalogo selezionato di circa due dozzine di fornitori sotto Integrazioni più usate, in un unico elenco con in cima quelli che puoi già collegare oggi. La ricerca lo filtra per nome, descrizione o categoria (CRM, commercio, supporto, produttività, marketing, pagamenti, software gestionale svizzero). La maggior parte delle voci sono server MCP; alcune, tra cui Bexio, weclapp e lexoffice, sono importazioni OpenAPI, e ogni voce ha un chip MCP o API che indica di quale tipo si tratta.

Ogni voce ha un badge di affidabilità e un'indicazione sull'autenticazione. I badge sono Ufficiale (l'endpoint è quello del fornitore stesso, preso dalla sua documentazione o dalla sua voce nel registro), Verificato e Community. Oggi tutte le voci del catalogo hanno il badge Ufficiale. L'indicazione sull'autenticazione è Senza login, Chiave API oppure OAuth (presto).

Ogni URL del catalogo è stato testato direttamente dal backend di botts.ai: ha portato a termine un handshake MCP completo oppure ha risposto con una richiesta di autenticazione che dimostra che l'URL e il trasporto sono reali. Le voci il cui unico login supportato è OAuth sono visibili ma disattivate, perché il client MCP non esegue ancora un flusso OAuth interattivo. Per lo stesso motivo pratico sono disattivate anche le voci che richiedono più intestazioni personalizzate di quante il modulo ne possa salvare.

Server MCP

Il Model Context Protocol (MCP) è uno standard aperto per mettere strumenti a disposizione degli assistenti IA. Invece di descrivere tu ogni endpoint, indichi a botts.ai un server MCP remoto e botts.ai chiede al server cosa sa fare.

Collegare un server

1. Scegli Server MCP al passaggio 1, oppure scegli un fornitore MCP dal catalogo.
2. Inserisci l'URL del server (ad esempio https://api.example.com/mcp/) e un Nome del server. Nome e descrizione vengono presi dal server al momento della connessione e puoi modificarli.
3. Imposta l'Autenticazione se il server la richiede: Nessuna, Bearer Token, Basic Auth o Intestazione Personalizzata (vedi Autenticazione). Login Token funziona solo per le connessioni API HTTP, e le connessioni MCP non hanno il campo Intestazioni aggiuntive.
4. Esegui la verifica della connessione. botts.ai completa un handshake MCP ed elenca gli strumenti del server.

Non tutti i server rispondono allo stesso indirizzo: alcuni su /mcp, altri su /mcp/. Se la verifica o il caricamento degli strumenti non riesce all'indirizzo che hai inserito, botts.ai riprova una volta con la barra finale aggiunta o tolta e, se così va meglio, inserisce per te nel campo la variante che funziona.

Importare gli strumenti

Rilevare gli strumenti di un server non li attiva. Nel passaggio Importa, clicca su Carica i tool: botts.ai chiede al server i suoi strumenti e li elenca con le loro descrizioni. Al primo caricamento tutti gli strumenti sono spuntati; togli la spunta a quelli che non vuoi, poi clicca su Salva (resta disattivato finché non è spuntato almeno uno strumento). Per cambiare la selezione in seguito, espandi il numero di strumenti sul riquadro della connessione, clicca su Gestisci tool, poi su Ricarica e Salva. Ogni strumento importato diventa un normale strumento dell'agente per ogni agente che ha attivato questa connessione.

Gli strumenti vengono registrati con un nome dotato di prefisso, servername__toolname, così due server che offrono entrambi uno strumento search non entrano mai in conflitto.

Quando un server cambia

botts.ai salva le definizioni degli strumenti che hai importato, e i tuoi agenti usano esattamente quelle. Se in seguito il server aggiunge, modifica o rimuove strumenti, per i tuoi agenti non cambia nulla finché un admin non apre Gestisci tool, clicca su Ricarica e salva.

Con la ricarica, gli strumenti che avevi importato restano spuntati finché il server li offre ancora, quelli che il server non offre più scompaiono e quelli nuovi arrivano senza spunta, così nulla di nuovo viene mai approvato automaticamente. Il salvataggio adotta le descrizioni e gli schemi di input attuali del server per gli strumenti spuntati, quindi leggili prima di salvare. È una scelta voluta: la descrizione di uno strumento è un'istruzione per il tuo modello, quindi un server che ridefinisce uno strumento senza avvisare potrebbe altrimenti cambiare il comportamento del tuo agente.

Se cambi l'URL del server di una connessione, o passi la sua credenziale da un segreto dell'organizzazione a uno personale o viceversa, i suoi strumenti importati vengono rimossi. La dashboard mostra allora «Server modificato: ricarica e conferma i tool.»

Connessioni API HTTP

Una connessione API HTTP è un URL di base più un insieme di endpoint. Le credenziali si configurano una volta sola sulla connessione e valgono per tutti i suoi endpoint.

Endpoint

Ogni endpoint della connessione diventa uno strumento che l'agente può chiamare:

Ogni endpoint il cui metodo non è GET è contrassegnato dal badge writes, e l'elenco degli endpoint mostra quanti di essi scrivono dati (per esempio «5 endpoint · 2 in scrittura»). Un endpoint senza descrizione viene segnalato, perché l'IA non ha alcuna base per sceglierlo.

Importare da OpenAPI

Se l'API pubblica una specifica OpenAPI, non devi inserire gli endpoint a mano.

1. Crea o modifica una connessione API HTTP e trova Importa da OpenAPI sotto l'elenco degli endpoint.
2. Indica l'URL della specifica (ad esempio https://api.example.com/openapi.json). Vengono letti sia JSON sia YAML, e botts.ai cerca automaticamente una specifica sotto il tuo URL di base e ti avvisa quando ne trova una. La specifica deve essere scaricabile da un URL: non c'è un campo in cui incollarla, quindi una specifica che hai solo in locale va prima pubblicata in un posto raggiungibile.
3. Controlla gli endpoint proposti. La ricerca restringe l'elenco, e All / None selezionano in blocco.
4. Importa la tua selezione.

Gli endpoint che scrivono dati non sono preselezionati. Li scegli tu, consapevolmente. Se una specifica ha più di 25 endpoint di lettura, nessuno è preselezionato: cerca quelli che ti servono e spuntali. Il campo di ricerca compare quando una specifica ha più di 12 endpoint, e All / None agiscono sui risultati della ricerca attuale.

Parametri

Ogni parametro ha un nome, un tipo (string, number, integer o boolean), una descrizione per l'IA e un'opzione che lo rende obbligatorio. I parametri diventano la firma della funzione dello strumento: il modello legge nomi, tipi e descrizioni per decidere quali valori estrarre dalla conversazione. Descrizioni precise migliorano direttamente l'affidabilità con cui l'agente compila gli argomenti.

Due opzioni cambiano ciò che vede il modello:

• Limita ai valori consentiti trasforma un parametro in un elenco fisso di opzioni, così il modello non può inventarsi uno stato o una categoria che la tua API non accetta.
• Fisso trasforma un parametro in una costante che l'IA non vede mai e non può cambiare. Viene inviato a ogni chiamata e il valore può essere un riferimento $secret:key. Usalo per ID tenant, numeri di conto e altri valori che appartengono alla connessione e non alla conversazione.

I parametri derivati da un segnaposto {param} nel percorso sono gestiti dal percorso stesso: rimuovi il segnaposto per rimuovere il parametro.

Autenticazione

I campi token, password e valore dell'intestazione accettano tutti riferimenti $secret:key, e ogni campo ha un chip $secret che te ne inserisce uno. Puoi anche creare un segreto direttamente lì, senza lasciare il modulo. Salva sempre le credenziali come segreti invece di incollarle in chiaro.

Login Token

Alcune API non rilasciano chiavi a lunga durata: invii le credenziali a un endpoint di login e usi il token che ricevi. L'autenticazione Login Token lo fa per te.

Un token in cache che viene rifiutato prima della scadenza (perché revocato, ruotato o perché il sistema a monte è stato riavviato) fa scattare un nuovo login automatico e una sola ripetizione della richiesta.

Ambito dell'autenticazione: condivisa o per utente

Ogni connessione usa una credenziale condivisa oppure una personale. Non lo scegli a parte: dipende dal segreto che inserisci nei campi Auth.

Quando un segreto è richiamato, il modulo mostra sopra i campi Auth quale dei due ambiti vale, e il riquadro della connessione lo indica accanto all'URL. Quando crei un segreto direttamente dal chip $secret, è il suo interruttore Org / Personale a rendere la connessione valida per tutta l'organizzazione o per utente.

Per utente permette a un team di condividere una connessione mentre ogni persona agisce a proprio nome nel sistema esterno. Ha due conseguenze da tenere presenti: non funziona sugli agenti pubblici (chi visita un sito web non ha un account botts.ai) e non fa nulla per un membro che non ha un segreto personale salvato con la chiave della connessione. Solo un Admin o un Proprietario può creare segreti, quindi è un admin a salvare la credenziale di ciascun collega con l'ambito Solo {name} (vedi Segreti). Per testare una connessione per utente o caricarne gli strumenti, l'admin ha bisogno di un proprio segreto personale con la stessa chiave; altrimenti la verifica segnala Servono le tue credenziali.

Una connessione per utente risolve solo i segreti propri di ciascun membro, quindi mescolare nei campi Auth un segreto personale con segreti dell'organizzazione non funzionerebbe per nessuno. Il modulo ti avvisa quando i campi sono misti e non ti permette di salvare.

Come vengono inviate le richieste

• GET e DELETE: gli argomenti dello strumento vengono inviati come parametri di query nell'URL, uniti a un'eventuale query string già presente nell'endpoint.
• POST, PUT e PATCH: gli argomenti dello strumento vengono inviati come body JSON della richiesta.
• Variabili di percorso: se il percorso contiene {param} e il modello fornisce un argomento corrispondente, questo viene codificato (percent-encoding), inserito nell'URL e rimosso dagli argomenti rimanenti. Esempio: orders/{order_id} con order_id: 1234 diventa orders/1234.
• Segreti: i riferimenti $secret:key nell'URL, nelle intestazioni e nei campi di autenticazione vengono risolti al momento della chiamata. Se un segreto richiamato non esiste, il segnaposto viene inviato come testo letterale.
• Timeout: in chat, le chiamate vanno in timeout dopo 30 secondi. In voce (telefono e voce nel widget), una chiamata a uno strumento viene interrotta dopo 15 secondi e all'agente viene detto che il tempo è scaduto.

Risposte e gestione degli errori

• Successo (2xx): il body della risposta viene passato al modello così com'è (il JSON viene serializzato, il testo semplice resta testo semplice). Le risposte molto grandi vengono troncate a circa 50'000 caratteri, mantenendo l'inizio e la fine, così un singolo risultato troppo grande non può soffocare la conversazione. In voce il limite è molto più stretto: tutti i risultati degli strumenti di un turno si dividono circa 24 KB, quindi dai una pipeline di risposta agli endpoint usati da un agente telefonico o vocale.
• Errori HTTP (4xx/5xx): per motivi di sicurezza il body della risposta viene nascosto al modello. All'agente viene detto solo The external API returned HTTP <status>., più un breve suggerimento ricavato dal solo codice di stato che gli indica cosa fare dopo e di non inventare i dati.
• Errori di connessione: l'agente vede The external API call failed. e un suggerimento che gli dice di segnalare l'integrazione come non raggiungibile invece di tirare a indovinare.

Quindi tutto ciò che vuoi che l'agente legga e riferisca al cliente deve tornare con un codice di stato 2xx. Per esempio, se un prodotto è esaurito, restituisci 200 con {"in_stock": false, "restock_date": "2026-09-01"} invece di un 404.

Poiché le connessioni possono avere effetti collaterali (prenotare un appuntamento, creare un ticket), la piattaforma non le ripete mai automaticamente e non riesegue un turno di conversazione dopo che una di esse è stata eseguita.

Pipeline di risposta

Alcune API rispondono in modo corretto ma poco utile: cento record quando all'agente ne servono cinque, o cinquanta campi quando ne contano due. Una pipeline di risposta sfoltisce la risposta prima che il modello la veda, riducendo sia i costi sia la confusione.

Apri Pipeline di risposta (avanzato) su un endpoint e inserisci un elenco JSON di passaggi, applicati in ordine:

Un argomento letto da un passaggio search o filter viene usato solo dalla pipeline e non viene inviato alla tua API, quindi puoi aggiungerlo come parametro extra sull'endpoint.

[
  { "step": "project", "fields": ["id", "name", "status"] },
  { "step": "search",  "arg": "query", "over": ["name"], "min_score": 60 },
  { "step": "sort",    "by": "name", "order": "asc" },
  { "step": "top",     "n": 5 },
  { "step": "render",  "format": "tsv", "empty_text": "No matching records." }
]

La pipeline viene validata al salvataggio, quindi un passaggio non valido viene rifiutato già in fase di configurazione e non a metà conversazione.

Sicurezza: endpoint bloccati

Per evitare abusi, gli endpoint delle connessioni sono soggetti a restrizioni:

• Sono consentiti solo URL http:// e https://.
• Prima di ogni chiamata il nome host viene risolto e verificato. Gli endpoint che puntano a reti private, localhost, indirizzi link-local o di metadati cloud, o ad altri intervalli interni o riservati vengono bloccati, così come i nomi host che non si riescono a risolvere.

Una chiamata bloccata restituisce Endpoint blocked by security policy. In parole semplici: le tue connessioni possono raggiungere la rete Internet pubblica, ma non host interni o privati. Lo stesso controllo vale per gli URL dei server MCP. Se devi integrare un'infrastruttura dedicata o interna, vedi Strumenti managed.

Testare una connessione

Il test avviene su due livelli, e la finestra di test li presenta come due domande separate.

Livello 1: la connessione funziona? Per un server MCP è un handshake che dimostra raggiungibilità e accesso valido, senza bisogno di parametri. Per un'API HTTP è una chiamata all'URL di base. L'esito viene comunicato in modo chiaro: La connessione funziona, Server non raggiungibile, Accesso negato, Server error, Indirizzo bloccato, Invalid URL, Secret mancante oppure Servono le tue credenziali (una connessione per utente per cui non hai un segreto personale).

Un URL di base che risponde senza verificare le credenziali dà un ulteriore esito, Server raggiungibile: l'indirizzo esiste, ma non dice nulla sulla tua chiave. Non è un errore, ed è proprio per questo che esiste il livello 2.

Livello 2: il tool è configurato correttamente? Scegli un endpoint o uno strumento rilevato ed eseguilo. I parametri sono precompilati con valori di esempio presi dallo schema, quindi la maggior parte dei test richiede un solo clic. Puoi modificarli in un modulo o come JSON grezzo, e passare da una panoramica leggibile del risultato al payload grezzo. Se l'endpoint ha una pipeline di risposta, il risultato è ciò che l'agente riceverebbe dopo la pipeline, e una pipeline non valida compare come Il tool segnala un errore. Un test dalla dashboard attende la tua API fino a 10 secondi, meno dei 30 secondi di una chiamata nella chat dal vivo.

Un endpoint che scrive dati ti chiede una conferma prima di essere eseguito, perché il test è una chiamata reale sul tuo sistema reale.

Per testare serve il ruolo Admin o Proprietario. Quando il test diretto va a buon fine, usa la chat di prova dell'agente per una verifica end-to-end: controlla che l'agente scelga lo strumento al momento giusto e ricavi correttamente i parametri. Per conservare questa verifica, salva la conversazione come test (vedi Test). Nelle esecuzioni dei test le connessioni partono disattivate e sono contrassegnate con Può eseguire azioni reali: se ne attivi una, ogni test la chiama davvero, senza nuovi tentativi. Le connessioni per utente non sono disponibili nei test.

Collegare gli strumenti agli agenti

Le connessioni stanno a livello di organizzazione; ogni agente sceglie le connessioni che usa:

1. Apri l'agente nell'editor dell'agente (scheda Configura).
2. Espandi la sezione Strumenti. Elenca tutte le connessioni della tua organizzazione (ogni server MCP e ogni API HTTP), ciascuna con un interruttore, e l'intestazione della sezione mostra quante sono collegate.
3. Attiva le connessioni che questo agente deve usare.

Attivare una connessione dà all'agente tutti gli strumenti importati su di essa. Per tenere uno strumento lontano dai tuoi agenti, non includerlo nell'importazione della connessione.

Se non esiste ancora nessuno strumento, la sezione rimanda alla pagina Integrazioni. Chi ha il ruolo Builder può collegare e scollegare strumenti qui, anche se non può crearne di nuovi.

Una connessione per utente mostra il badge Per utente e ti indica con quali chiavi ogni membro deve avere un segreto personale per poterla usare.

Una connessione può anche essere disattivata a livello globale per tutta l'organizzazione. In quel caso mostra il badge Disabilitato globalmente nell'editor dell'agente e viene ignorata da tutti gli agenti finché non viene riattivata, indipendentemente dagli interruttori dei singoli agenti. Al momento la dashboard non ha un interruttore per questa impostazione globale; è disponibile solo tramite l'API.

Strumenti managed

Una connessione ha un Tipo che comprende anche Managed. Le connessioni managed vengono predisposte dallo staff della piattaforma botts.ai per infrastrutture dedicate o interne, ad esempio un ERP o un bridge verso i sistemi di produzione che gira nel tuo ambiente. Rispetto alle connessioni normali, quelle managed:

• Aggirano il blocco delle reti private, quindi possono raggiungere host interni.
• Ripetono automaticamente la chiamata in caso di errori di connessione (fino a 3 tentativi, a 1 secondo di distanza). Le connessioni normali non ripetono mai le chiamate.
• Mostrano un badge Managed color ambra nell'elenco.

Non puoi creare connessioni managed in autonomia; il selettore del Tipo è riservato allo staff della piattaforma. Se hai bisogno di un'integrazione dedicata con sistemi interni, contatta botts.ai.

Segreti

La scheda Segreti è l'archivio sicuro per le chiavi API e le altre credenziali che servono alle tue connessioni. Ogni segreto ha:

• Nome: un'etichetta visualizzata, ad es. «Acme API Key».
• Chiave: l'identificativo che richiami come $secret:key, ad es. acme_api_key.
• Valore: la credenziale vera e propria.

Proprietà di sicurezza

• I valori dei segreti sono cifrati a riposo su infrastruttura svizzera, e botts.ai non te li mostra mai più. Naturalmente vengono inviati al sistema presso cui servono ad autenticarsi, che si trova ovunque operi quel fornitore: la residenza di una credenziale segue quindi la connessione su cui la usi.
• I valori sono di sola scrittura: dopo la creazione, né la dashboard né l'API restituiscono mai il valore di un segreto. L'elenco mostra solo nome, chiave e ambito. Nei risultati dei test, i valori dei segreti risolti vengono oscurati nell'URL visualizzato, ma il body della risposta viene mostrato senza modifiche, quindi un endpoint che rimanda indietro la richiesta li restituisce per intero.
• Non esiste una funzione di modifica. Per ruotare un segreto, eliminalo e ricrealo con la stessa chiave. Le connessioni che richiamano $secret:key continuano a funzionare senza modifiche.
• I riferimenti $secret:key vengono risolti al momento della chiamata nell'URL, nei valori delle intestazioni e nei campi di autenticazione.

Ambiti

Usa segreti dell'organizzazione per ogni connessione che un agente usa nelle conversazioni dal vivo su un canale pubblico. I segreti personali vengono risolti solo per le richieste del membro a cui appartengono, quindi la conversazione di chi visita il sito web non troverebbe nulla.

Il terzo ambito risponde a un problema pratico: una connessione per utente funziona solo per i membri che hanno un segreto personale con la sua chiave. Un admin può usare Aggiungi per un altro utente su un segreto personale esistente (una chiave senza un valore per tutta l'organizzazione) per salvare la stessa chiave per un altro membro, così la connessione funziona per tutto il team senza che nessuno debba condividere una password. In questo caso la chiave resta vincolata a quella originale; si impostano solo l'utente e il valore.

Una chiave duplicata nello stesso ambito viene rifiutata; scegli una chiave univoca per ogni segreto.

Buone pratiche

1. Scrivi descrizioni chiare. L'agente decide quando usare uno strumento in base alla sua descrizione. Descrizioni vaghe portano a usare lo strumento nel momento sbagliato. Lo stesso vale per le descrizioni dei parametri: orientano ciò che il modello estrae.
2. Importa gli endpoint che ti servono, non tutti. Ogni strumento collegato è testo nel prompt del modello. Venti endpoint dove ne basterebbero tre rendono l'agente più lento, più costoso e meno deciso.
3. Mantieni veloci le API. L'agente aspetta la risposta prima di continuare la conversazione (fino a 30 secondi in chat, 15 secondi in voce). Le API lente creano pause imbarazzanti.
4. Restituisci le informazioni utili con uno stato 2xx. L'agente non vede mai il body di una risposta 4xx o 5xx, solo il codice di stato. Se «non trovato» o «esaurito» sono cose che l'agente deve spiegare al cliente, restituiscile come 200 con un body JSON descrittivo.
5. Sfoltisci le risposte grandi con una pipeline invece di costringere il modello a farsi strada tra tutti quei dati.
6. Salva le credenziali come segreti. Non incollare mai chiavi API direttamente negli URL o nelle intestazioni; usa riferimenti $secret:key, così restano cifrate e oscurate.
7. Testa prima entrambi i livelli. Verifica la connessione, poi l'endpoint, poi usa la chat di prova dell'agente per confermare che l'agente attivi lo strumento al momento giusto, e salva quella conversazione come test.
8. Parti dal semplice. Comincia con una connessione e un paio di endpoint, ed espandi man mano che capisci come il tuo agente li usa.

Ultimo aggiornamento: 4 ottobre 2026