Best practice operative per le integrazioni Mattone

Queste 7 regole si applicano a ogni integrazione, indipendentemente dal pezzo che stai configurando. Non sono linee guida vaghe: derivano da errori reali accaduti sul campo. Seguirle previene l’80% dei problemi prima che si presentino e riduce il tempo di debug quando qualcosa va storto.

​

1. Segui l’ordine, non improvvisare

Ogni connessione ha un “prima” e un “dopo”: l’ordine dei passi non è arbitrario ma riflette dipendenze reali tra i componenti. Saltare un passo, anche uno che sembra minore, rompe silenziosamente ciò che viene dopo. Esempio classico: aggiungere un custom tool a Conduit senza configurare la skill corrispondente. L’agente ignora il tool o tenta un percorso nativo inaffidabile, e il problema non produce un errore visibile, il tool semplicemente non funziona.

​

2. Verifica SEMPRE i log dell’esito reale

Quello che mostra l’interfaccia di un’app è spesso una semplificazione, o peggio, un messaggio fuorviante. I log mostrano l’esito reale. Non fidarti di ciò che l’app ti dice: fidati di ciò che i log mostrano. Controlla sempre: Vercel runtime logs, risposta grezza dell’API (spesso include il codice di errore), console del browser.

​

3. Ogni deploy/fix deve mostrare problema + soluzione

Un errore silenzioso o un messaggio generico come “qualcosa è andato storto” non è accettabile. Ogni scenario di errore deve:

• Mostrare all’utente (studente o operatore) cosa è andato storto in modo comprensibile
• Indicare come risolverlo o chi contattare
• Essere documentato nella pagina Troubleshooting corrispondente con il codice di errore e la soluzione

​

4. Ogni tool Conduit va SEMPRE con la sua skill

Un custom tool senza skill è inutile. L’agente Conduit non sa quando usarlo, quindi o lo ignora completamente o cade su un percorso nativo che non è stato pensato per quel caso d’uso. La sequenza corretta è sempre:

1. Crea il tool
2. Crea la skill che specifica quando e come usarlo
3. Verifica che l’agente risponda correttamente a un input di test

​

5. Credenziali mai in chat né nei repo

Le chiavi API, i token e le password dei clienti non vanno mai in una chat (WhatsApp, Slack, email) né committate in un repository. Vanno sempre e solo nel Vault, il magazzino cifrato delle credenziali. Se uno studente ti invia una credenziale in chat, fai due cose immediatamente:

1. Salvala nel Vault
2. Chiedi allo studente di ruotare la chiave, quella inviata in chat va considerata compromessa

Per le istruzioni su come salvare e recuperare le credenziali consulta la pagina Credenziali e Vault.

​

6. Prima di dire “fatto”, smoke test

L’onboarding non è completo finché non hai verificato personalmente che i tre elementi chiave funzionano:

• ✅ Apertura porta: il comando di apertura eseguito da Conduit aziona fisicamente la serratura
• ✅ Knowledge Base: l’agente risponde correttamente a una domanda sull’appartamento usando le informazioni della KB
• ✅ Link di pagamento: Stripe genera correttamente un link di pagamento per lo studente

Per la checklist completa vedi la pagina Verifica finale.

​

7. Conosci le pagine di riferimento prima di iniziare

Ogni integrazione ha una pagina dedicata in Mattone Docs con la lista degli endpoint attivi, i codici di errore noti e le soluzioni già documentate. Prima di improvvisare una soluzione o aprire un ticket, consulta la pagina di riferimento corrispondente: spesso il problema è già stato incontrato e risolto.