Habla con
tu documentación
Captura de pantalla. La plantilla ejecutándose en local.
- Modelos
- ink-2, sonic-3.6
- Idiomas
- Inglés, español, francés, hindi, japonés
- Licencia
- Apache-2.0
- Stack
- HonoNode.jsWeb ComponentsesbuildBM25 or OpenAI embeddings
- Productos de Cartesia
- Managed AgentsInk 2Sonic 3.6
Qué hace
El widget funciona en cualquier sitio y no necesita otras bibliotecas. El servidor es una pequeña app de Node que guarda el índice de búsqueda en un archivo local. Por defecto, la búsqueda compara palabras clave. Con una clave de OpenAI compara por significado, lo que entiende mejor las preguntas formuladas con otras palabras. Al volver a indexar solo se procesan las páginas que cambiaron.
Ejecútalo tú mismo
Ejecuta la demo
Ejecuta los comandos de abajo con Node 22.22 o posterior, abre
http://localhost:4512, pulsa Ask the docs y luego Start talking. El sitio de demo es una copia de dos páginas dedocs.cartesia.ai.Variables de entorno - CARTESIA_API_KEY
play.cartesia.ai/keys- OPENAI_API_KEY
- Opcional. Cambia la búsqueda a embeddings de
text-embedding-3-small - CARTESIA_AGENT_ID
- Lo escribe
npm run setup:agent - CARTESIA_TOOL_IDS
- Opcional. Lo escribe
npm run setup:agentpara que sepas qué herramientas borrar. Nada lo lee - ALLOWED_ORIGINS
- Los orígenes de tu documentación, separados por comas
- PUBLIC_URL, TRUST_PROXY
- Detrás de un proxy. Con
TRUST_PROXY=1, el límite de peticiones usa la dirección que añadió tu proxy
Indexa tu documentación
Ejecuta
npm run ingest--./my-docs--base-url/docs/ para una carpeta de archivos .md o .mdx, onpm run ingest -- --sitemapcon la URL de tu sitemap para un sitio publicado.Añade la etiqueta script
Despliega el servidor en cualquier host que ejecute Node 22.22 o posterior, añade una etiqueta script que apunte a su
widget.jsy pon el origen de tu documentación enALLOWED_ORIGINS.
Créalo con tu agente de programación
Un prompt que le dice a tu agente de programación por dónde empezar y qué leer primero.
Prompt
Add a voice assistant to my documentation site with a Cartesia Managed Agent. Start from https:/ 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:/ to get one.
Cómo funciona
Por qué funciona así
La búsqueda se ejecuta en el navegador del visitante
Cartesia solo llama a herramientas que están en una dirección HTTPS pública. Una herramienta de cliente se ejecuta en el navegador del visitante, que pasa la pregunta a tu servidor, así que la demo funciona en localhost sin túnel.
Los resultados caben en 4.096 bytes
Cartesia rechaza los resultados de herramientas de cliente de más de 4.096 bytes. server/search.ts ordena las secciones, da un pequeño impulso a la página actual y mete las cuatro mejores en un resultado de menos de 3.800 bytes.
El límite de peticiones es la protección real
El servidor rechaza otros sitios web comprobando la cabecera Origin, pero un script puede enviar cualquier cabecera. Lo que protege tu cuenta es el límite de 4 tokens por minuto y 30 por hora por dirección IP.
Adáptalo a ti
Prompt y herramientas
Edita scripts/agent-config.ts y luego ejecuta npm run setup:agent -- --force. Crea un agente nuevo y dos herramientas nuevas y sobrescribe CARTESIA_TOOL_IDS, así que copia antes los ids antiguos y borra el agente y las herramientas antiguos en play.cartesia.ai. Los nombres de las herramientas también están en widget/src/tools.ts, así que cambia los dos.
Idioma
Pon AGENT_LANGUAGE a es, fr, hi o ja antes de la configuración. El prompt ya responde en el idioma del visitante.
Almacén de vectores
server/store.ts es el único archivo que lee o escribe el índice. Sustitúyelo por pgvector o SQLite cuando unos pocos miles de secciones no basten.
Únete a los equipos que dan el salto a Cartesia
Preguntas
¿Pueden otros sitios web usar mi widget y mi clave de API?
No. Solo los sitios que pongas en ALLOWED_ORIGINS, más la dirección del propio servidor, pueden iniciar una llamada. Tus claves de API se quedan en el servidor, y el navegador recibe un token que dura 60 segundos y solo sirve para llamadas a agentes.
¿No puede hacer esto la base de conocimiento integrada de Cartesia?
También puede responder a partir de tu documentación. Esta plantilla busca en tu propio servidor, así que cada resultado lleva el enlace de la página y la sección que el widget necesita para desplazarse hasta ella.
¿Funciona en Docusaurus, Mintlify o Nextra?
Sí, en cualquier sitio donde puedas añadir una etiqueta script. Indexa el sitio desde su sitemap para que los enlaces a secciones coincidan con sus encabezados. El widget sigue el modo oscuro del sitio o el ajuste del sistema del visitante.
¿Por qué se corta la llamada al hacer clic en un enlace a otra página?
La llamada vive en la página, y un sitio de varias páginas se recarga al navegar. Por eso, durante una llamada, las fuentes de otras páginas se abren en una pestaña nueva.
¿Se graban las llamadas de los visitantes?
Sí. Cartesia graba el audio y la transcripción de cada llamada de agente. Avisa a tus visitantes y borra las llamadas que no necesites con la API de Cartesia.
¿Hay una guía paso a paso de esta plantilla?
Sí. La receta recorre el código, el README explica la instalación, las variables de entorno y el despliegue, y la documentación de herramientas de cliente explica la parte de Cartesia.
Más del cookbook
Empieza hoy
Habla con un experto.
Habla con nuestro equipo y descubre cómo puede ayudarte Cartesia a crear experiencias de voz de primer nivel.
Empieza a crear.
Accede a nuestros modelos mediante API y lleva un agente de voz a producción en minutos.