Troubleshooting Conduit: leak KB, tool ignorati e bug noti

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

Bug UPDATE Knowledge Base (save silenzioso)

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:

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.

Metodo troubleshooting

Le 5 mosse

Custom tools (regola tool↔skill)

Perché ripiega sul nativo

PMS & CRM

Conduit AI

Numeri & WhatsApp (WABA)

Dati & Revenue

Pagamenti & Vendita diretta

Smart Lock

Troubleshooting Conduit: leak KB, tool ignorati e bug noti

Tabella sintomo → causa → soluzione

Bug noti

Quando aprire un ticket al supporto Conduit

Metodo troubleshooting

Custom tools (regola tool↔skill)

​Tabella sintomo → causa → soluzione

​Bug noti

​Quando aprire un ticket al supporto Conduit

Metodo troubleshooting

Custom tools (regola tool↔skill)

Tabella sintomo → causa → soluzione

Bug noti

Quando aprire un ticket al supporto Conduit