> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting Conduit: leak KB, tool ignorati e bug noti
> Tabella sintomo-causa-soluzione per i problemi Conduit più comuni: leak di Knowledge Base, tool non attivati, workflow fermi e bug noti con workaround.
Usa questa pagina come prima tappa quando qualcosa non funziona nell'agente Conduit di uno studente. I problemi più frequenti rientrano in due categorie: errori di scope sulla KB (l'AI risponde con informazioni dell'appartamento sbagliato) e tool ignorati perché la skill abbinata è assente o mal formulata. Per la maggior parte dei casi puoi risolvere senza aprire un ticket al supporto Conduit, segui la colonna "Soluzione" nell'ordine indicato.
## Tabella sintomo → causa → soluzione
| Sintomo | Causa probabile | Soluzione |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **L'AI dà informazioni dell'appartamento sbagliato** | KB globale senza scope `entity_ids` | Riscopa la directory KB sul `listing_id` corretto. Aggiungi `entity_ids: [listingId]` alla directory e verifica che tutti gli articoli siano dentro la cartella scopata, non al livello radice. |
| **Risponde su una prenotazione sbagliata** | `reservationIds` vuoto oppure OTA senza listing scope nella KB | Fix scope lato Conduit engineering + verifica che la KB sia per-listing con `entity_ids` corretti. Apri ticket con workspace ID e `listing_id`. |
| **Dice "occupato" quando l'appartamento è libero** | Tool nativo invece di `check-availability`, skill assente, o parsing disponibilità errato | Aggiungi il tool `check-availability` al workspace e configura la skill abbinata. Se il tool c'è ma non viene chiamato, controlla che la skill sia attiva e riformula il trigger. Verifica il parsing delle date. |
| **Il salvataggio di un articolo KB fallisce silenziosamente** | Bug noto su operazione UPDATE in Conduit | Non aggiornare l'articolo esistente. Apri un ticket al supporto Conduit e nel frattempo crea un **nuovo articolo** con il contenuto aggiornato, poi archivia il vecchio. |
| **Il tool non si attiva mai** | Skill assente oppure skill non in stato attivo | Vai nella sezione Skills del workspace, verifica che la skill abbinata al tool esista e sia abilitata. Se non esiste, aggiungila. Se esiste ma è disabilitata, attivala e ritesta. |
| **L'agente usa il path nativo invece del tool** | Skill mancante o formulazione troppo vaga | La skill c'è ma non è abbastanza precisa nel definire il trigger. Riscrivila con istruzioni più specifiche su quando usare il tool (es. «ogni volta che l'ospite chiede di aprire la porta o di accedere all'appartamento»). |
| **Il guardrail non si attiva** | Guardrail mal formulato oppure non salvato correttamente | Apri Agent settings e verifica che il guardrail sia presente nell'array `guardrails`. Se è presente ma non funziona, riformula la regola in modo più esplicito e diretto. Testa con più varianti del messaggio. |
| **Il workflow non parte** | Trigger non configurato correttamente oppure workflow non in stato attivo | Apri il workflow in dashboard e verifica che il tipo di trigger sia corretto (`AI_TRIGGER`, evento prenotazione, ecc.) e che il workflow risulti **attivo**. Un workflow salvato ma non attivato non si avvia mai. |
## Bug noti
**Comportamento:** quando modifichi un articolo KB esistente e salvi, la UI mostra un feedback positivo ma le modifiche non vengono persistite. L'articolo rimane con il contenuto originale.
**Workaround:** non aggiornare articoli esistenti. Crea sempre un nuovo articolo con il contenuto aggiornato e archivia o elimina il vecchio. Apri un ticket al supporto Conduit includendo workspace ID e nome dell'articolo per tracciare il bug.
## Quando aprire un ticket al supporto Conduit
Per problemi non presenti in questa tabella o per bug Conduit confermati, apri un ticket al supporto Conduit includendo **obbligatoriamente**:
* Workspace ID dello studente
* `listing_id` dell'appartamento coinvolto
* Timestamp della conversazione o dell'evento anomalo
* Log della conversazione (screenshot o export)
Senza questi dati il supporto Conduit non può diagnosticare il problema. Raccoglili prima di aprire il ticket.
Prima di aprire un ticket, controlla sempre se il problema è nella tabella sopra e se il workaround risolve il caso. Il supporto Conduit ha tempi di risposta variabili, risolvere in autonomia quando possibile evita blocchi operativi durante l'onboarding.
**▷ Prompt Claude Code: Debug Conduit** · incolla in Claude Code:
```text theme={null}
Contesto: in questa sessione di Claude Code NON hai il repo/codice caricato.
Per prima cosa apri il repo `~/Projects/api-kross-mattone` (conduit-reasoning,
conduit-custom-tool, catalog.json) e LEGGI le pagine mattone-docs
/troubleshooting/metodo e /integrazioni/conduit/troubleshooting; per le prove
reali usa l'MCP Conduit (simulate_conversation, list_calls, get_contact_detail).
Poi procedi:
Applica il metodo di mattone-docs /troubleshooting/metodo a questo problema
Conduit: [DESCRIVI IL SINTOMO, es. "l'AI dà il WiFi di un'altra casa" /
"dice occupato su date libere" / "al telefono non trova la prenotazione" /
"non salva la KB"]. LEGGI la prova reale prima di concludere: per la chat il
TRACE di simulate_conversation (quale skill/tool ha usato); per la voce
list_calls (source retell); per lo scope get_contact_detail(include_reservations
:true) vs list_contact_reservations. Isola: KB scope? skill non attaccata?
lingua voice Multilingual? save bug? Proponi il fix e, se è lato Conduit,
prepara l'esempio riproducibile da mandare a Raniel/Yash.
```
Le 5 mosse
Perché ripiega sul nativo