> ## 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.

# Step 3 · Configurare l'agente Conduit per lo studente

> Imposta l'agente AI Conduit: KB per-listing da Notion, custom tool con skill abbinate, workflow automatici e canale telefonico/WABA per lo studente.

Conduit è il cervello AI che risponde agli ospiti per conto dello studente. Ogni studente ha il proprio workspace isolato composto da KB, agente e tool. La configurazione va eseguita in un ordine preciso: prima la base di conoscenza, poi i tool con le relative skill, poi i workflow, e infine il canale telefonico/WABA. Saltare o invertire questi passaggi causa comportamenti imprevisti nell'agente.

<Warning>
  **GATE DI ATTIVAZIONE, due condizioni OBBLIGATORIE prima di attivare il workspace Conduit.** A chi fa l'onboarding: **non attivare il workspace/agente Conduit** di uno studente se non ha **entrambe**:

  1. **Contratto "Servizio AI Ospiti" FIRMATO**: l'**Addendum "Servizio AI Ospiti"** (Mattone.co LLC ↔ studente) che regola **canone €9/Listing/mese**, **Costi a Consumo**, **durata minima 12 mesi** e **autorizzazione all'addebito**. Verifica firma + **Data attivazione** (sezione "Dettagli Attivazione" del contratto).
  2. **Carta a file nella piattaforma**: lo studente deve aver **aggiunto il metodo di pagamento** (carta) nell'area billing della piattaforma. Senza carta, l'addebito ricorrente non può partire.

  **Se manca anche solo UNA delle due → NON attivare. Nessuna eccezione.** L'attivazione fa **decorrere il canone dalla Data di attivazione**.

  **Dove si legge lo stato:** `contract_signed = true` **e** presenza della **carta** (metodo di pagamento) nella piattaforma / area billing dello studente. Lo stato **"contratto firmato"** va registrato **nella piattaforma** (app.mattone.co), non solo qui: quando confermi la firma, flaggalo (o carica il PDF firmato) nella scheda dello studente, la piattaforma è la fonte unica, lo **studente stesso vede il suo contratto** nella sua area e l'attivazione del billing resta legata a quel flag.
</Warning>

<Warning>
  **PRIMA DI TUTTO, accesso Admin Mattone (obbligatorio, facile da dimenticare).** Appena creato il workspace Conduit di uno studente, aggiungi **`francesco@mattone.co`** come **Admin** (dashboard Conduit → membri/team → invita come **Admin**). È l'unico modo per garantire che il team Mattone abbia sempre accesso a quel workspace.

  ⚠️ **Non esiste un'API** per aggiungere membri: va fatto **a mano** nella dashboard. Se te ne dimentichi, il team **perde l'accesso** (dalla UI) a quel workspace. **Verifica** che l'Admin Mattone sia nella lista membri prima di considerare il workspace pronto.

  *(È in corso una richiesta a Conduit per aggiungere `francesco@mattone.co` come Admin in automatico a ogni nuovo workspace, a livello di organizzazione; finché non è attiva, resta questo step manuale.)*
</Warning>

<Warning>
  KB globale = leak tra appartamenti. Ogni KB deve avere lo scope sulla directory per-listing, non creare mai una KB condivisa tra più appartamenti dello stesso studente.
</Warning>

## Ordine corretto

<Steps>
  <Step title="Costruisci la KB con il bridge Notion → Conduit (OBBLIGATORIO)">
    Questo è un passo **obbligatorio** del setup Conduit, **non** opzionale: **senza KB, l'agente non ha le informazioni degli appartamenti** (WiFi, indirizzo, accesso, regole, listino) e non può rispondere agli ospiti.

    **Ordine:**

    1. Il **registro appartamenti su Notion** è collegato e completo (Step 1 dell'onboarding).
    2. Il **bridge Notion → Conduit** genera la **KB per-appartamento** dentro il workspace Conduit: una cartella per ogni appartamento, con gli `entity_id` scopati sul `listing_id` corrispondente.
    3. Da lì l'**agente risponde con i dati giusti**, quelli di quell'appartamento e basta.

    Lo scope per-listing garantisce che Conduit risponda all'ospite del Loft Navigli A **solo** con le informazioni del Loft Navigli A. **Non creare mai una KB globale**: causa leak tra appartamenti (accessi sbagliati, listino errato, regole di un altro immobile).

    → Come funziona il bridge: [Notion → Bridge Conduit](/integrazioni/notion/bridge-conduit) · Regole KB: [KB per-listing](/integrazioni/conduit/kb)
  </Step>

  <Step title="Custom tool con skill abbinate">
    Per ogni tool che vuoi attivare (Kross, Shelly, Stripe), devi configurare **sempre anche la skill di prompting** corrispondente. Senza la skill, l'agente non sa quando e come usare il tool e lo ignora completamente.

    Monta i tool nell'ordine in cui li hai configurati negli step precedenti:

    * **Kross tool** → skill `kross-reservation-reader` (richiede Step 2 completato)
    * **Shelly tool** o **SwitchBot tool** → skill `smart-lock-opener` (richiede Step 4 completato)
    * **Stripe tool** → skill `payment-link-generator` (richiede Step 5 completato)

    Se uno step non è ancora completato, monta i tool corrispondenti solo dopo aver terminato quello step.

    → Guida dettagliata: [Custom tool e skill](/integrazioni/conduit/custom-tools)
  </Step>

  <Step title="Workflow">
    Configura i workflow per le automazioni deterministiche: late check-in/out, messaggi di benvenuto programmati, promemoria per la restituzione delle chiavi e qualsiasi altra sequenza che non richiede ragionamento dell'agente ma solo esecuzione di regole fisse.

    I workflow si attivano su trigger (es. *X ore prima del check-in*) e possono usare i tool già montati nello step precedente.

    → Guida dettagliata: [Workflow Conduit](/integrazioni/conduit/workflow)
  </Step>

  <Step title="Telefonia + WABA">
    Questo è un percorso separato che richiede intervento del supporto Conduit. Il tempo medio di attivazione è **circa 1 settimana** dalla richiesta. Pianificalo in anticipo: **apri il ticket Conduit presto**, appena completata la KB e i tool.

    **Chi fa cosa (crystal clear):**

    * **Lo studente** → **richiede il numero** dal **portale Conduit**, indicando il **prefisso della propria città** (numero italiano dedicato).
    * **Il team Mattone** → **supporta la parte WABA/Meta**: registrazione **WhatsApp Business API con Meta** e **collegamento al Business Manager Facebook** (meglio nuovo), tramite Conduit support.
    * Warm transfer al telefono dello studente per le chiamate che l'agente non gestisce.

    Lo standard, già a doc: il numero **italiano** è quello guest-facing (WhatsApp, chiamate, annunci OTA); l'agente VoiceAI può girare su un numero di backend Conduit con **forwarding** dal numero italiano, è normale, l'ospite vede sempre il numero italiano.

    <Info>
      **Cosa dire allo studente, numero IT + WhatsApp ufficiale (WABA)**

      Serve circa **1 settimana**, quindi partiamo subito. Passa allo studente questi passi, plain:

      1. **Non comprare una SIM** e **non usare il numero WhatsApp fai-da-te che ti propone Facebook.**
      2. **Sei tu a richiedere il numero dal portale Conduit**, indicando il **prefisso della tua città** (serve un **numero italiano dedicato** al servizio): se non sai dove cliccare, te lo mostriamo.
      3. Ottenuto il numero, la **registrazione per WhatsApp Business (WABA) con Meta la seguiamo noi insieme a te** (team Mattone), non da solo.
      4. Poi lo **colleghiamo a un Business Manager Facebook** (meglio nuovo): se ti serve, ti guidiamo a crearlo.
      5. Tienilo presente: lo **stesso numero italiano** varrà per **WhatsApp, chiamate e come riferimento sugli annunci OTA**.

      Da dire chiaro: *"Il numero lo richiedi tu dal portale Conduit; la registrazione ufficiale con Meta la facciamo insieme. È il tuo numero ufficiale verso gli ospiti: ci vuole circa una settimana, per questo partiamo subito."*

      Prerequisiti da chiedere allo studente in anticipo: un **numero non già usato su WhatsApp** (personale o business), **accesso a Facebook Business Manager** come amministratore, e un **documento aziendale** (es. visura) per la verifica Meta.
    </Info>

    Apri il ticket al supporto Conduit appena hai completato la KB e i tool, in questo modo quando il canale è pronto, il workspace è già configurato correttamente.

    → Guida dettagliata: [Telefonia e WABA](/integrazioni/conduit/telefonia-waba)
  </Step>
</Steps>

<Note>
  Per la documentazione completa dell'integrazione Conduit, architettura del workspace, limiti, gestione degli errori e best practice, consulta [Conduit · Panoramica](/integrazioni/conduit/panoramica).
</Note>

***

Step completato? Procedi con → [Step 4 · Smart check-in](/onboarding/4-smart-checkin)

<Tip>
  **▷ Prompt Claude Code: Monta l'agente Conduit**  ·  incolla in Claude Code:
</Tip>

```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` (skill onboarding,
custom tool + catalog.json, provisioning) e `~/Projects/mattone-platform`
(bridge KB da Notion), e LEGGI la pagina mattone-docs /onboarding/3-conduit;
per testare usa l'MCP Conduit (simulate_conversation). Poi procedi:

Guidami nello step 3 (Conduit) per lo studente [NOME], seguendo mattone-docs
/onboarding/3-conduit. GATE DI ATTIVAZIONE, da verificare PRIMA di attivare o
provisionare qualsiasi cosa: (a) contratto "Servizio AI Ospiti" FIRMATO
(contract_signed = true) E (b) carta a file nella piattaforma (metodo di
pagamento aggiunto dallo studente, area billing). Se manca ANCHE SOLO UNA delle
due, FERMATI e dimmelo: NON attivare il workspace, nessuna eccezione. Solo a
gate superato, procedi. Rispetta l'ordine: prima KB per-listing dal Notion
(bridge, mai globale), poi custom tool, OGNUNO con la sua prompting skill,
poi workflow, poi telefonia/WABA. Verifica che la api_key Kross vera sia già
nel Vault PRIMA di iniettare i tool. Poi controlla via MCP che le 4 skill core
siano ATTACCATE al Guest Agent (skill_ids != 0) e che i nomi tool siano
canonici. Testa con simulate_conversation e mostrami il trace: deve usare
load_skill -> tool giusto -> risposta corretta, non il nativo. Chiedimi
workspace_id/agent_id se non li hai. Per la telefonia/WABA ricordami di aprire
SUBITO il ticket Conduit (attivazione ~1 settimana) e passami il box "Cosa dire
allo studente" (numero IT dal portale Conduit col prefisso città -> WABA con
Meta col nostro supporto -> Business Manager Facebook) da inoltrare allo studente.
```

<CardGroup cols={2}>
  <Card title="Provisioning (piattaforma)" icon="arrow-up-right-from-square" href="https://app.mattone.co/connessioni">Sezione AI / provisioning studente</Card>
  <Card title="Dashboard Conduit" icon="robot">Workspace dell'agente (KB, tool, skill, voice)</Card>
</CardGroup>