Parla con
la tua documentazione

Q: Altri siti possono usare il mio widget e la mia chiave API?

No. Solo i siti che elenchi in ALLOWED_ORIGINS, più l'indirizzo del server stesso, possono avviare una chiamata. Le tue chiavi API restano sul server, e il browser riceve un token che dura 60 secondi e funziona solo per le chiamate agli agenti.

Un tag script aggiunge un pulsante vocale alla tua documentazione. Un Cartesia Managed Agent cerca nelle tue pagine, risponde ad alta voce e scorre la pagina fino alla sezione citata.

Vedi su GitHub

Sito di documentazione demo con due pagine, Client tools e Tools, e il pannello vocale aperto. Il visitatore ha chiesto quanto può essere grande il risultato di un client tool, l'agente ha risposto fino a 4096 byte, e la sezione citata è in vista ed evidenziata in verde

Screenshot. Il template in esecuzione in locale.

Modelli: ink-2, sonic-3.6
Lingue: Inglese, spagnolo, francese, hindi, giapponese
Licenza: Apache-2.0
Stack: HonoNode.jsWeb ComponentsesbuildBM25 or OpenAI embeddings
Prodotti Cartesia: Managed AgentsInk 2Sonic 3.6

Cosa fa

Il widget funziona su qualsiasi sito e non ha bisogno di altre librerie. Il server è una piccola app Node che tiene l'indice di ricerca in un file locale. Per impostazione predefinita la ricerca confronta parole chiave. Con una chiave OpenAI confronta il significato, e gestisce meglio le domande formulate in modo diverso dalla documentazione. Una nuova indicizzazione elabora solo le pagine cambiate.

Eseguilo tu

1
Esegui la demo
Esegui i comandi qui sotto con Node 22.22 o successivo, apri http://localhost:4512, premi Ask the docs e poi Start talking. Il sito demo è una copia di due pagine di 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
Variabili d'ambiente
CARTESIA_API_KEY
play.cartesia.ai/keys
OPENAI_API_KEY
Opzionale. Passa la ricerca agli embedding text-embedding-3-small
CARTESIA_AGENT_ID
Scritta da npm run setup:agent
CARTESIA_TOOL_IDS
Opzionale. Scritta da npm run setup:agent così sai quali tool eliminare. L'app non la legge
ALLOWED_ORIGINS
Le origini della tua documentazione, separate da virgole
PUBLIC_URL, TRUST_PROXY
Dietro un proxy. Con TRUST_PROXY=1 il limite di frequenza usa l'indirizzo aggiunto dal tuo proxy
Indicizza la tua documentazione
Esegui npm run ingest -- ./my-docs --base-url /docs/ per una cartella di file .md o .mdx, oppure npm run ingest -- --sitemap con l'URL della tua sitemap per un sito online.
Aggiungi il tag script
Distribuisci il server su qualsiasi host che esegua Node 22.22 o successivo, aggiungi un tag script che punti al suo widget.js e imposta ALLOWED_ORIGINS sull'origine della tua documentazione.

Crealo con il tuo agente di programmazione

Un prompt che dice al tuo agente di programmazione da dove partire e cosa leggere per primo.

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.

Come funziona

Tag scriptCarica il web component cartesia-docs-agent

Ink 2Ascolta la domanda del visitatore

search_docsUn client tool che ordina le tue sezioni sul tuo server, per parole chiave o con gli embedding

show_sourceScorre alla sezione citata e la evidenzia

Sonic 3.6Pronuncia una risposta di due o tre frasi

Perché funziona così

La ricerca gira nel browser del visitatore

Cartesia chiama solo tool che si trovano a un indirizzo HTTPS pubblico. Un client tool invece gira nel browser del visitatore, che passa la domanda al tuo server, quindi la demo funziona su localhost senza tunnel.

I risultati stanno sotto i 4.096 byte

Cartesia rifiuta i risultati dei client tool oltre i 4.096 byte. server/search.ts ordina le sezioni, dà una piccola spinta alla pagina corrente e mette le prime quattro in un risultato sotto i 3.800 byte.

La vera protezione è il limite di frequenza

Il server respinge gli altri siti controllando l'header Origin, ma uno script può inviare qualsiasi header. Quello che protegge il tuo account è il limite di 4 token al minuto e 30 all'ora per indirizzo IP.

Personalizzalo

Prompt e tool

Modifica scripts/agent-config.ts, poi esegui npm run setup:agent -- --force. Il comando crea un nuovo agente e due nuovi tool e sovrascrive CARTESIA_TOOL_IDS, quindi prima copia i vecchi id ed elimina l'agente e i tool vecchi su play.cartesia.ai. I nomi dei tool sono anche in widget/src/tools.ts, quindi cambiali in entrambi i file.

Lingua

Imposta AGENT_LANGUAGE su es, fr, hi o ja prima della configurazione. Il prompt risponde già nella lingua del visitatore.

Archivio vettoriale

server/store.ts è l'unico file che legge o scrive l'indice. Sostituiscilo con pgvector o SQLite quando qualche migliaio di sezioni non basta.

Unisciti ai team che passano a Cartesia

Al primo posto

nelle classifiche Speech Arena e Speech to Text di Artificial Analysis

Domande

Altri siti possono usare il mio widget e la mia chiave API?

No. Solo i siti che elenchi in ALLOWED_ORIGINS, più l'indirizzo del server stesso, possono avviare una chiamata. Le tue chiavi API restano sul server, e il browser riceve un token che dura 60 secondi e funziona solo per le chiamate agli agenti.

La knowledge base integrata di Cartesia non può farlo?

Può anche rispondere dalla tua documentazione. Questo template cerca invece sul tuo server, così ogni risultato porta il link della pagina e la sezione che servono al widget per scorrere fin lì.

Funziona con Docusaurus, Mintlify o Nextra?

Sì, ovunque tu possa aggiungere un tag script. Indicizza il sito dalla sua sitemap così i link alle sezioni corrispondono ai suoi titoli. Il widget segue la modalità scura del sito o l'impostazione di sistema del visitatore.

Perché la chiamata finisce quando clicco un link a un'altra pagina?

La chiamata vive nella pagina, e un sito con più pagine si ricarica a ogni navigazione. Durante una chiamata, le fonti su altre pagine si aprono invece in una nuova scheda.

Le chiamate dei visitatori vengono registrate?

Sì. Cartesia registra l'audio e la trascrizione di ogni chiamata dell'agente. Avvisa i tuoi visitatori e cancella le chiamate che non ti servono con l'API di Cartesia.

Esiste una guida passo passo per questo template?

Sì. La ricetta spiega il codice, il README copre configurazione, variabili d'ambiente e distribuzione, e la documentazione sui client tool spiega la parte Cartesia.