Build a Support Agent with Vercel AI SDKEjecutar el curso de Vercel AI SDK localmente
Usa esta página para ejecutar el agente de soporte al cliente extraído del curso de Vercel AI SDK en tu computadora y obtener una respuesta con tu propia clave de OpenAI y el proyecto de Supabase que construiste en el curso. Un servidor Node ejecuta todo el proyecto: sirve la página de chat y responde sus preguntas, para que tus claves permanezcan en ese servidor y nunca lleguen al navegador. Una cosa diferencia esto del editor de Scrimba: Node no lee .env por sí solo, así que el script de inicio necesita una bandera.
Lo que necesitas primero
Instala una versión LTS compatible de Node.js. Se recomienda Node 24 e incluye npm.
Verifica que ambos comandos funcionen. Tus números de versión pueden ser diferentes:
$ node --version
v24.18.0
$ npm --version
11.18.0También necesitas tres valores:
- una clave de API de OpenAI, en una cuenta con facturación configurada, porque OpenAI genera cada respuesta;
- la URL de tu proyecto de Supabase, que se muestra en el diálogo Connect del proyecto;
- la clave secreta de ese proyecto, que comienza con
sb_secret_, en Settings > API Keys.
Usa el proyecto de Supabase del curso. El agente busca los documentos de ayuda de Scrimba almacenados allí a través de la función match_documents del proyecto. Si ya no tienes ese proyecto, el servidor aún necesita una URL de Supabase y una clave secreta para iniciarse, y los valores de un proyecto nuevo funcionarán. Solo las preguntas sobre Scrimba usan Supabase, así que las preguntas generales aún obtienen respuestas de búsqueda web, mientras que las preguntas sobre Scrimba no encuentran nada que buscar.
La clave heredada service_role también funciona hasta que Supabase la retire, previsto para finales de 2026. Ver Claves de API de Supabase.
node --version y npm --version ambos impriman una versión. Luego recopila tres cosas: tu clave de OpenAI, la URL de tu proyecto de Supabase y la clave secreta de ese proyecto. Usa el proyecto de Supabase que construiste en el curso; uno nuevo no tiene documentos que el agente pueda buscar.
Instala los paquetes
Abre una terminal en la carpeta extraída, la que contiene package.json y server.js, e instala las versiones exactas de paquetes que usó el curso:
$ cd path-to-your-extracted-project
$ npm ci
added 94 packages, and audited 95 packages in 4snpm también reporta algunas vulnerabilidades en esos paquetes. No impiden que el proyecto se ejecute en tu computadora. No ejecutes npm audit fix; actualiza paquetes contra los que se escribió el código del curso.
npm ci en la carpeta con package.json. Termina diciendo cuántos paquetes agregó. Si npm dice que solo puede instalar con un package-lock.json existente, estás en la carpeta incorrecta.
Cambia el script de inicio
En Scrimba, el editor entregaba tus claves al servidor. En tu computadora, Node lee .env solo cuando se lo pides, y config.js detiene el servidor de inmediato si falta la clave de OpenAI. Abre package.json y cambia el script de inicio de:
"start": "node server.js"a:
"start": "node --env-file=.env server.js"La bandera está incorporada en Node, así que no hay nada extra que instalar.
package.json, añade --env-file=.env al script de inicio exactamente como se muestra, y guarda el archivo. Nada más en el proyecto cambia. Añade tus claves a .env
Crea .env junto a package.json con tus tres valores:
OPENAI_API_KEY=tu-clave-de-api-de-openai
SUPABASE_URL=https://tu-proyecto.supabase.co
SUPABASE_SERVICE_ROLE_KEY=tu-clave-secreta-de-supabase
PORT=3000El código aún usa el nombre heredado SUPABASE_SERVICE_ROLE_KEY; pon tu clave secreta allí sin renombrar nada. Tiene que ser la clave secreta o la clave heredada service_role, no la clave publicable, que está destinada al código del navegador y no tiene el acceso que el servidor necesita. PORT es opcional: sin él, el servidor usa 3000.
Crea .gitignore junto a package.json y añade:
.env
node_modules/Una clave que llega a un repositorio de Git permanece en su historial incluso después de que elimines el archivo. El manual de Git cubre el hábito en ignorar archivos y buenas prácticas.
Mantén la clave de Supabase en el servidor
Tu clave secreta de Supabase puede leer y cambiar todo en tu base de datos. En este proyecto solo el servidor la lee, y ese es el único lugar seguro para ella: nunca la copies en client.js, y nunca hagas commit ni compartas .env.
.env junto a package.json con tus valores en las primeras tres líneas, luego lista .env en .gitignore para que Git nunca lo guarde. Inicia el agente y haz una pregunta
Inicia el servidor:
$ npm start
> start
> node --env-file=.env server.js
Server listening at http://localhost:3000Abre http://localhost:3000, o el puerto que configuraste en .env. La página Support AI Chatbot tiene un cuadro para tu pregunta y un botón Ask. Haz una pregunta sobre Scrimba, como cómo restablecer tu contraseña. La página muestra Thinking… mientras el agente trabaja, luego la respuesta. Cuando la respuesta viene de tus documentos de Supabase, View Sources debajo de ella lista los pasajes que usó, cada uno con una puntuación de similitud: OpenAI y Supabase ambos funcionan. Una pregunta general, sobre noticias por ejemplo, se responde con búsqueda web y lista páginas web en su lugar; esa solo necesita OpenAI. El capítulo de RAG explica por qué el agente busca cosas antes de responder.
Si la respuesta dice I encountered an error while processing your request using tool calling. Please try again later., la página no puede decirte por qué. La razón está en la terminal donde se ejecuta el servidor, bajo la línea [ToolBased] Error in RAG process:.
Detén el servidor con Ctrl+C.
npm start, espera a Server listening at http://localhost:3000, y abre esa dirección. Haz una pregunta sobre Scrimba y espera la respuesta. Si la respuesta dice que encontró un error, lee la terminal, no la página.
Solución de problemas
El servidor se detiene de inmediato con Missing OPENAI_API_KEY environment variable: Node no cargó .env. Verifica que el script de inicio diga node --env-file=.env server.js y que el nombre en .env sea exactamente OPENAI_API_KEY. SUPABASE_SERVICE_ROLE_KEY is missing or invalid y SUPABASE_URL is missing or invalid significan lo mismo para esos nombres.
node: .env: not found: El script de inicio es correcto, pero no hay .env junto a package.json. Verifica que el archivo se llame exactamente .env, no .env.txt.
Invalid supabaseUrl: Must be a valid HTTP or HTTPS URL.: SUPABASE_URL tiene que ser la dirección completa del diálogo Connect, comenzando con https://.
Error: listen EADDRINUSE: address already in use :::3000: Otro programa está usando el puerto 3000, a menudo una ejecución anterior de este servidor en otra terminal. Detenlo con Ctrl+C, o configura PORT=3001 en .env, inicia de nuevo y abre http://localhost:3001.
La respuesta dice que encontró un error, y la terminal dice Incorrect API key provided: OpenAI rechazó la clave con un 401. Cópiala de nuevo de tu cuenta de OpenAI, verifica que no haya sido eliminada, luego reinicia el servidor.
La terminal dice You exceeded your current quota: La clave funciona, pero la cuenta de OpenAI no tiene crédito para gastar. Añade facturación en tu cuenta de OpenAI, luego pregunta de nuevo.
Una pregunta sobre Scrimba obtiene una respuesta sin fuentes, y la terminal muestra una línea que comienza con [Tool:KB] Error: OpenAI funciona, pero Supabase no devolvió los documentos del curso. Verifica que la URL y la clave secreta provengan del mismo proyecto, que la clave sea la clave secreta o service_role en lugar de la publicable, y que el proyecto aún tenga los documentos del curso y su función match_documents.
La terminal dice que el modelo gpt-4o no está disponible: OpenAI detiene gpt-4o el 14 de enero de 2027, y nombra gpt-6-luna como su reemplazo. Cambia ANSWERING_MODEL en constants.js al reemplazo en la página de depreciaciones de OpenAI. Deja EMBEDDING_MODEL_NAME como text-embedding-3-small: los documentos en Supabase fueron incrustados con él, y un modelo de embedding diferente encuentra coincidencias pobres sin ningún error.
npm start, el problema está en package.json o .env. Si la página responde con una disculpa, la razón está en la terminal del servidor.