> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# KB per l'agente vocale ElevenLabs

> Collega un agente conversazionale AI ElevenLabs specifico dell'area di lavoro alla tua knowledge base Switchbord.

Switchbord può replicare la knowledge base della tua area di lavoro in un agente
conversazionale AI ElevenLabs, così le chiamate vocali rispondono utilizzando gli stessi
fatti che Margaret vede in chat. Questo documento descrive la configurazione iniziale, il flusso di
sincronizzazione e i controlli operativi.

## Cosa viene sincronizzato

Ogni riga in `workspace_knowledge_entries` il cui array `tags` contiene **`kb`**
o **`memory`** è una candidata. In particolare:

* Le voci curate di FAQ/documenti/policy che gli operatori scrivono tramite l'interfaccia della Knowledge Base
  (`kb`).
* Le note a lungo termine che Margaret ha salvato tramite lo strumento `writeWorkspaceMemory`
  (`memory`).

Ogni voce viene inviata alla knowledge base dell'agente ElevenLabs configurato. L'ID
del documento remoto viene salvato in `workspace_knowledge_entries.elevenlabs_document_id`,
così le sincronizzazioni ripetute sono idempotenti — le nuove righe vengono create, quelle
esistenti vengono aggiornate senza duplicati.

## Configurazione

1. **Ottieni una API key ElevenLabs** da
   [elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys).
2. **Crea (o scegli) un agente conversazionale AI** su
   [elevenlabs.io/app/conversational-ai](https://elevenlabs.io/app/conversational-ai).
   Copia il suo agent ID (formato: `agent_...`).
3. In Switchbord, vai su **Impostazioni → Integrazioni → AI → Voce (ElevenLabs)**.
4. Incolla la API key (memorizzata per area di lavoro nel Supabase Vault) e
   l'agent ID (memorizzato in `workspaces.elevenlabs_agent_id`).
5. Clicca su **Test connessione** — questo richiama
   `GET /v1/convai/agents/{agent_id}` con la tua chiave e restituisce il nome
   dell'agente in caso di successo.

## Flusso di sincronizzazione

### Dall'interfaccia delle impostazioni

La stessa pagina contiene una card **Sincronizzazione knowledge base** con due pulsanti:

* **Plan (dry run)** — legge la KB dell'area di lavoro e riporta quali voci
  verrebbero create o aggiornate, senza toccare ElevenLabs.
* **Sincronizza ora** — legge la API key dal vault, poi invia una richiesta POST (o PATCH)
  per ogni voce candidata alla KB dell'agente ElevenLabs.

### Da Margaret

Gli operatori con il ruolo **admin** possono chiedere a Margaret:

> "Sincronizza la nostra KB con l'agente ElevenLabs."

Margaret richiama lo strumento `syncElevenLabsKnowledge`. Per default esegue un dry run
che riporta il piano in chat. Impostando `dryRun: false` viene mostrata una card di
approvazione HITL secondo il pattern ToolApprovalCard — una volta approvata, Margaret
esegue l'invio effettivo.

### Dalla API

```bash theme={null}
curl -X POST https://app.switchbord.io/api/elevenlabs/kb/sync \
  -H "Content-Type: application/json" \
  --data '{"dryRun": false}' \
  --cookie "..."
```

Struttura della risposta:

```json theme={null}
{
  "dryRun": false,
  "agentId": "agent_abc",
  "candidates": 12,
  "succeeded": 12,
  "failed": 0,
  "actions": [
    { "entryId": "…", "title": "Orari di apertura", "verb": "create", "ok": true, "documentId": "doc_…" }
  ]
}
```

## Sicurezza

* La API key risiede nel Supabase Vault per area di lavoro (tipo di secret
  `elevenlabs-api-key`). Solo l'indizio mascherato viene restituito all'interfaccia.
* L'agent ID è in chiaro su `public.workspaces` — non è un secret.
* Gli endpoint di sincronizzazione e impostazioni richiedono `requireSettingsAccess` (ruolo
  owner/admin). Lo strumento `syncElevenLabsKnowledge` di Margaret richiede inoltre
  il ruolo di accesso agli strumenti admin e un'approvazione HITL prima di un invio effettivo.

## Limitazioni note (ship 1)

* La struttura del payload dei documenti della KB ElevenLabs potrebbe evolversi. La rotta di sincronizzazione ha come default
  `dryRun: true`, così gli operatori possono visualizzare in anteprima prima di chiamare la API remota.
* Non esiste ancora un percorso di eliminazione — rimuovere una riga in Switchbord non elimina il
  documento da ElevenLabs. Tracciato tramite
  [BORD-TBD](https://linear.app/gbvai/issue/BORD-322).
* Il test di connessione al momento richiama `GET /v1/convai/agents/{agent_id}`. Se
  ElevenLabs modifica i propri codici di errore, l'interfaccia mostra lo stato HTTP grezzo.