Skip to main content
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.
  2. Crie (ou escolha) um agente de IA conversacional em 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

Formato da resposta:

​
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.
  • 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.