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

# Knowledge Base de agente de voz do ElevenLabs

> Conecte um agente de IA conversacional do ElevenLabs específico do workspace à sua base de conhecimento do Switchbord.

O Switchbord pode espelhar a base de conhecimento do seu workspace em um
agente de IA conversacional do ElevenLabs, de forma que as chamadas de voz
respondam com base nos mesmos fatos que a Margaret vê no chat. Este documento
cobre a configuração inicial, o fluxo de sincronização e os controles
operacionais.

## O que é sincronizado

Toda linha em `workspace_knowledge_entries` cujo array `tags` contenha **`kb`**
ou **`memory`** é uma candidata. Ou seja:

* As entradas de FAQ/documentação/política que os operadores escrevem pela
  interface da Knowledge Base (`kb`).
* Notas de longo prazo que a Margaret salvou via a ferramenta
  `writeWorkspaceMemory` (`memory`).

Cada entrada é enviada para a base de conhecimento do agente ElevenLabs
configurado. O ID do documento remoto é persistido em
`workspace_knowledge_entries.elevenlabs_document_id`, de forma que
sincronizações repetidas sejam idempotentes — novas linhas são criadas, e
linhas existentes são atualizadas no lugar.

## Configuração

1. **Obtenha uma API key do ElevenLabs** em
   [elevenlabs.io/app/settings/api-keys](https://elevenlabs.io/app/settings/api-keys).
2. **Crie (ou escolha) um agente de IA conversacional** em
   [elevenlabs.io/app/conversational-ai](https://elevenlabs.io/app/conversational-ai).
   Copie o ID do agente (formato: `agent_...`).
3. No Switchbord, acesse **Settings → Integrations → AI → Voice (ElevenLabs)**.
4. Cole a API key (armazenada por workspace no Supabase Vault) e o
   ID do agente (armazenado em `workspaces.elevenlabs_agent_id`).
5. Clique em **Test connection** — isso chama
   `GET /v1/convai/agents/{agent_id}` com sua key e reporta o nome do agente
   em caso de sucesso.

## Fluxo de sincronização

### Pela interface de configurações

A mesma página tem um card **Knowledge-base sync** com dois botões:

* **Plan (dry run)** — lê a KB do workspace e reporta quais entradas
  seriam criadas ou atualizadas, sem tocar no ElevenLabs.
* **Sync now** — lê a API key do vault e então faz POST (ou PATCH) de
  cada entrada candidata para a KB do agente ElevenLabs.

### Pela Margaret

Operadores com o papel de **admin** podem pedir à Margaret:

> "Envie nossa KB para o agente do ElevenLabs."

A Margaret chama a ferramenta `syncElevenLabsKnowledge`. O padrão é um dry run
que reporta o plano no chat. Definir `dryRun: false` exibe um card de
aprovação HITL no padrão ToolApprovalCard — uma vez aprovado, a Margaret
faz o envio real.

### Pela API

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

Formato da resposta:

```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_…" }
  ]
}
```

## Segurança

* A API key vive no Supabase Vault por workspace (secret do tipo
  `elevenlabs-api-key`). Apenas a dica mascarada é retornada para a interface.
* O ID do agente é texto simples em `public.workspaces` — não é um segredo.
* Os endpoints de sincronização e configurações exigem `requireSettingsAccess`
  (papel de owner/admin). A ferramenta `syncElevenLabsKnowledge` da Margaret
  exige adicionalmente o papel de acesso a ferramentas de admin e uma
  aprovação HITL antes de um envio real.

## Limitações conhecidas (versão 1)

* O formato do payload de documentos da KB do ElevenLabs pode evoluir. A rota
  de sincronização usa `dryRun: true` como padrão, para que os operadores
  possam pré-visualizar antes de acionar a API remota.
* Ainda não há caminho de exclusão — remover uma linha no Switchbord não
  remove o documento correspondente no ElevenLabs. Acompanhe em
  [BORD-TBD](https://linear.app/gbvai/issue/BORD-322).
* O teste de conexão atualmente chama `GET /v1/convai/agents/{agent_id}`. Se
  o ElevenLabs alterar seus códigos de erro, a interface exibe o status HTTP bruto.