Converse com
a sua documentação

Q: Outros sites podem usar meu widget e minha chave de API?

Não. Só os sites que você listar em ALLOWED_ORIGINS, mais o endereço do próprio servidor, podem iniciar uma chamada. Suas chaves de API ficam no servidor, e o navegador recebe um token que dura 60 segundos e só funciona para chamadas com agentes.

Uma tag script adiciona um botão de voz à sua documentação. Um Cartesia Managed Agent pesquisa suas páginas, responde em voz alta e rola a página até a seção que citou.

Ver no GitHub

Site de documentação de demonstração com duas páginas, Client tools e Tools, e o painel de voz aberto. O visitante perguntou qual o tamanho máximo do resultado de uma ferramenta de cliente, o agente respondeu até 4096 bytes, e a seção citada está rolada até a tela e destacada em verde

Captura de tela. O template rodando localmente.

Modelos: ink-2, sonic-3.6
Idiomas: Inglês, espanhol, francês, hindi, japonês
Licença: Apache-2.0
Stack: HonoNode.jsWeb ComponentsesbuildBM25 or OpenAI embeddings
Produtos da Cartesia: Managed AgentsInk 2Sonic 3.6

O que ele faz

O widget funciona em qualquer site e não precisa de outras bibliotecas. O servidor é um pequeno app Node que guarda o índice de busca em um arquivo local. Por padrão, a busca compara palavras-chave. Com uma chave da OpenAI, ela compara o significado, o que lida melhor com perguntas escritas de outro jeito que na documentação. Indexar de novo processa só as páginas que mudaram.

Rode você mesmo

1
Rode a demo
Rode os comandos abaixo com o Node 22.22 ou mais recente, abra http://localhost:4512, clique em Ask the docs e depois em Start talking. O site de demonstração é uma cópia de duas páginas de docs.cartesia.ai.
npx degit cartesia-ai/cookbook/examples/docs-voice-widget docs-voice-widget cd docs-voice-widget # add CARTESIA_API_KEY cp .env.example .env.local npm install # creates the agent and its two tools, saves the ids npm run setup:agent # indexes content/*.md into data/index.json npm run ingest npm run dev
Variáveis de ambiente
CARTESIA_API_KEY
play.cartesia.ai/keys
OPENAI_API_KEY
Opcional. Muda a busca para embeddings com text-embedding-3-small
CARTESIA_AGENT_ID
Gravado por npm run setup:agent
CARTESIA_TOOL_IDS
Opcional. Gravado por npm run setup:agent para você saber quais ferramentas apagar. Nada o lê
ALLOWED_ORIGINS
As origens da sua documentação, separadas por vírgula
PUBLIC_URL, TRUST_PROXY
Atrás de um proxy. TRUST_PROXY=1 aplica o limite de requisições pelo endereço que o seu proxy acrescentou
Indexe sua documentação
Rode npm run ingest -- ./my-docs --base-url /docs/ para uma pasta de arquivos .md ou .mdx, ou npm run ingest -- --sitemap com a URL do seu sitemap para um site no ar.
Adicione a tag script
Implante o servidor em qualquer host que rode Node 22.22 ou mais recente, adicione uma tag script apontando para o widget.js dele e defina ALLOWED_ORIGINS com a origem da sua documentação.

Crie com seu agente de programação

Um prompt que diz ao seu agente de programação por onde começar e o que ler primeiro.

Prompt

Claude Code Cursor Codex

Add a voice assistant to my documentation site with a Cartesia Managed Agent. Start from https://github.com/cartesia-ai/cookbook/tree/main/examples/docs-voice-widget and follow its AGENTS.md for the commands, files and rules. npm run setup:agent creates the agent and two client tools, search_docs and show_source. The widget gets a 60 second access token with only the agent grant from the Hono server and opens the Managed Agents WebSocket. search_docs results come from POST /api/search and must stay under 4,096 bytes. Index my docs with npm run ingest, either from a folder or with --sitemap. If I don't have a Cartesia API key yet, follow https://www.cartesia.ai/agent-quickstart.md to get one.

Como funciona

Tag scriptCarrega o web component cartesia-docs-agent

Ink 2Ouve a pergunta do visitante

search_docsUma ferramenta de cliente que ordena suas seções no seu servidor, por palavras-chave ou embeddings

show_sourceRola até a seção citada e a destaca

Sonic 3.6Fala uma resposta de duas ou três frases

Por que funciona assim

A busca roda no navegador do visitante

A Cartesia só chama ferramentas que ficam em um endereço HTTPS público. Uma ferramenta de cliente roda no navegador do visitante, que repassa a pergunta ao seu servidor, então a demonstração funciona em localhost sem túnel.

Os resultados cabem em menos de 4.096 bytes

A Cartesia rejeita resultados de ferramentas de cliente com mais de 4.096 bytes. server/search.ts ordena as seções, dá um pequeno peso extra à página atual e junta as quatro primeiras em um resultado com menos de 3.800 bytes.

O limite de requisições é a proteção de verdade

O servidor recusa outros sites verificando o cabeçalho Origin, mas um script pode enviar qualquer cabeçalho. O que protege sua conta é o limite de 4 tokens por minuto e 30 por hora por endereço IP.

Deixe com a sua cara

Prompt e ferramentas

Edite scripts/agent-config.ts e depois rode npm run setup:agent -- --force. Ele cria um novo agente e duas novas ferramentas e sobrescreve CARTESIA_TOOL_IDS, então copie os ids antigos antes e apague o agente e as ferramentas antigos em play.cartesia.ai. Os nomes das ferramentas também ficam em widget/src/tools.ts, então mude os dois.

Idioma

Defina AGENT_LANGUAGE como es, fr, hi ou ja antes da configuração. O prompt já responde no idioma do visitante.

Banco de vetores

server/store.ts é o único arquivo que lê ou grava o índice. Troque por pgvector ou SQLite quando alguns milhares de seções não forem suficientes.

Junte-se às equipes que estão migrando para a Cartesia

Em 1º lugar

nos rankings Speech Arena e Speech to Text da Artificial Analysis

Perguntas

Outros sites podem usar meu widget e minha chave de API?

Não. Só os sites que você listar em ALLOWED_ORIGINS, mais o endereço do próprio servidor, podem iniciar uma chamada. Suas chaves de API ficam no servidor, e o navegador recebe um token que dura 60 segundos e só funciona para chamadas com agentes.

A base de conhecimento integrada da Cartesia não faz isso?

Ela também responde a partir da sua documentação. Este template busca no seu próprio servidor, então cada resultado traz o link da página e a seção de que o widget precisa para rolar até ela.

Funciona no Docusaurus, no Mintlify ou no Nextra?

Sim, em qualquer lugar onde você possa adicionar uma tag script. Indexe o site pelo sitemap para que os links das seções batam com os títulos. O widget segue o modo escuro do site ou a configuração do sistema do visitante.

Por que a chamada termina quando clico em um link para outra página?

A chamada vive na página, e um site de várias páginas recarrega ao navegar. Durante uma chamada, fontes em outras páginas abrem em uma nova aba.

As chamadas dos visitantes são gravadas?

Sim. A Cartesia grava o áudio e a transcrição de cada chamada de agente. Avise seus visitantes e apague as chamadas de que não precisa pela API da Cartesia.

Existe um guia passo a passo deste template?

Sim. A receita explica o código, o README cobre a configuração, as variáveis de ambiente e a implantação, e a documentação de ferramentas de cliente explica o lado da Cartesia.