Parlez à
votre documentation

Q: D'autres sites peuvent-ils utiliser mon widget et ma clé API ?

Non. Seuls les sites listés dans ALLOWED_ORIGINS, plus l'adresse du serveur lui-même, peuvent lancer un appel. Vos clés API restent sur le serveur, et le navigateur reçoit un jeton valable 60 secondes qui ne sert qu'aux appels d'agents.

Une balise script ajoute un bouton vocal à votre documentation. Un Managed Agent Cartesia cherche dans vos pages, répond à voix haute et fait défiler la page jusqu'à la section qu'il cite.

Voir sur GitHub

Site de documentation de démo avec deux pages, Client tools et Tools, et le panneau vocal ouvert. Le visiteur a demandé quelle taille peut avoir le résultat d'un outil client, l'agent a répondu jusqu'à 4096 octets, et la section citée est visible à l'écran, teintée de vert

Capture d'écran. Le modèle lancé en local.

Modèles: ink-2, sonic-3.6
Langues: Anglais, espagnol, français, hindi, japonais
Licence: Apache-2.0
Stack technique: HonoNode.jsWeb ComponentsesbuildBM25 or OpenAI embeddings
Produits Cartesia: Managed AgentsInk 2Sonic 3.6

Ce qu'il fait

Le widget fonctionne sur n'importe quel site et n'a besoin d'aucune autre bibliothèque. Le serveur est une petite application Node qui garde l'index de recherche dans un fichier local. Par défaut, la recherche compare des mots-clés. Avec une clé OpenAI, elle compare le sens, ce qui gère mieux les questions formulées autrement que dans vos docs. Une nouvelle indexation ne traite que les pages modifiées.

Lancez-le vous-même

1
Lancez la démo
Lancez les commandes ci-dessous avec Node 22.22 ou plus récent, ouvrez http://localhost:4512, appuyez sur Ask the docs, puis sur Start talking. Le site de démo est une copie de deux pages 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
Variables d'environnement
CARTESIA_API_KEY
play.cartesia.ai/keys
OPENAI_API_KEY
Facultative. Fait passer la recherche aux embeddings text-embedding-3-small
CARTESIA_AGENT_ID
Écrite par npm run setup:agent
CARTESIA_TOOL_IDS
Facultative. Écrite par npm run setup:agent pour que vous sachiez quels outils supprimer. Rien ne la lit
ALLOWED_ORIGINS
Les origines de votre documentation, séparées par des virgules
PUBLIC_URL, TRUST_PROXY
Derrière un proxy. TRUST_PROXY=1 applique la limite de débit à l'adresse ajoutée par votre proxy
Indexez votre documentation
Lancez npm run ingest -- ./my-docs --base-url /docs/ pour un dossier de fichiers .md ou .mdx, ou npm run ingest -- --sitemap avec l'URL de votre sitemap pour un site en ligne.
Ajoutez la balise script
Déployez le serveur sur n'importe quel hébergeur qui exécute Node 22.22 ou plus récent, ajoutez une balise script qui pointe vers son widget.js et définissez ALLOWED_ORIGINS avec l'origine de votre documentation.

Créez-le avec votre agent de code

Un prompt qui indique à votre agent de code par où commencer et quoi lire en premier.

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.

Comment ça marche

Balise scriptCharge le composant web cartesia-docs-agent

Ink 2Entend la question du visiteur

search_docsUn outil client qui classe vos sections sur votre serveur, par mots-clés ou par embeddings

show_sourceDéfile jusqu'à la section citée et la colore

Sonic 3.6Prononce une réponse de deux ou trois phrases

Pourquoi ça fonctionne ainsi

La recherche tourne dans le navigateur du visiteur

Cartesia n'appelle que des outils situés à une adresse HTTPS publique. Un outil client tourne plutôt dans le navigateur du visiteur, qui transmet la question à votre serveur, donc la démo fonctionne sur localhost sans tunnel.

Les résultats tiennent sous 4 096 octets

Cartesia refuse les résultats d'outil client de plus de 4 096 octets. server/search.ts classe les sections, avantage un peu la page en cours et regroupe les quatre meilleures dans un résultat de moins de 3 800 octets.

La vraie protection, c'est la limite de débit

Le serveur refuse les autres sites en vérifiant l'en-tête Origin, mais un script peut envoyer n'importe quel en-tête. Ce qui protège votre compte, c'est la limite de 4 jetons par minute et 30 par heure par adresse IP.

Personnalisez-le

Prompt et outils

Modifiez scripts/agent-config.ts, puis lancez npm run setup:agent -- --force. La commande crée un nouvel agent et deux nouveaux outils, et écrase CARTESIA_TOOL_IDS : copiez d'abord les anciens id, puis supprimez l'ancien agent et ses outils sur play.cartesia.ai. Les noms d'outils se trouvent aussi dans widget/src/tools.ts, changez donc les deux.

Langue

Définissez AGENT_LANGUAGE à es, fr, hi ou ja avant la configuration. Le prompt répond déjà dans la langue du visiteur.

Base vectorielle

server/store.ts est le seul fichier qui lit ou écrit l'index. Remplacez-le par pgvector ou SQLite quand quelques milliers de sections ne suffisent plus.

Rejoignez les équipes qui passent à Cartesia

Classé numéro 1

dans les classements Speech Arena et Speech to Text d'Artificial Analysis

Questions

D'autres sites peuvent-ils utiliser mon widget et ma clé API ?

Non. Seuls les sites listés dans ALLOWED_ORIGINS, plus l'adresse du serveur lui-même, peuvent lancer un appel. Vos clés API restent sur le serveur, et le navigateur reçoit un jeton valable 60 secondes qui ne sert qu'aux appels d'agents.

La base de connaissances intégrée de Cartesia ne peut-elle pas faire ça ?

Elle peut aussi répondre à partir de vos docs. Ce modèle cherche plutôt sur votre propre serveur, donc chaque résultat porte le lien de la page et la section dont le widget a besoin pour y défiler.

Est-ce que ça fonctionne avec Docusaurus, Mintlify ou Nextra ?

Oui, partout où vous pouvez ajouter une balise script. Indexez le site depuis son sitemap pour que les liens de section correspondent à ses titres. Le widget suit le mode sombre du site, ou le réglage système du visiteur.

Pourquoi l'appel se termine-t-il quand je clique sur un lien vers une autre page ?

L'appel vit dans la page, et un site de plusieurs pages se recharge à chaque navigation. Pendant un appel, les sources situées sur d'autres pages s'ouvrent donc dans un nouvel onglet.

Les appels des visiteurs sont-ils enregistrés ?

Oui. Cartesia enregistre l'audio et la transcription de chaque appel d'agent. Prévenez vos visiteurs, et supprimez les appels inutiles avec l'API Cartesia.

Existe-t-il un guide pas à pas pour ce modèle ?

Oui. La recette parcourt le code, le README couvre l'installation, les variables d'environnement et le déploiement, et la documentation des outils client explique le côté Cartesia.