Ejecutar Agents localmente

Usa esta página para ejecutar un proyecto de Agents extraído en tu computadora. El bucle ReAct, el bucle de function-calling y la interfaz final usan la misma configuración de Vite, pero muestran sus resultados en lugares diferentes. Actualiza la búsqueda de la clave de OpenAI y el ID del modelo antiguo antes de iniciar el hito que tengas.

Qué necesitas primero

Instala una versión LTS compatible de Node.js. Se recomienda Node 24 e incluye npm; la exportación es un proyecto de Vite, así que Node y npm cubren todas las herramientas que necesita.

También necesitas una clave de API de OpenAI con facturación y acceso a modelos habilitados. El acceso a modelos se configura por proyecto en el panel de OpenAI: el proyecto al que pertenece tu clave debe permitir el modelo que configures a continuación. La clave en sí va en un archivo .env en un paso posterior.

JunoQué necesitas primero Instala la versión LTS de Node.js, que trae npm junto con ella. También necesitas una clave de API de OpenAI de una cuenta que pueda hacer solicitudes de modelos pagados. Reunir ambas antes de comenzar significa que nunca tendrás que parar a mitad de la configuración para encontrarlas, ¡cosa que siempre solía hacer!

JunoQué necesitas primero La exportación es un proyecto de Vite, así que Node LTS más npm es toda la cadena de herramientas. Tu clave de OpenAI va en .env un par de pasos a partir de ahora, y el acceso a modelos significa la lista de modelos permitidos en el proyecto de tu clave en el panel de OpenAI. Si verificas esa lista ahora, evitas el error más confuso después.

JunoQué necesitas primero Vite iniciará estos proyectos sin ninguna clave funcionando, lo que hace que una clave rota sea el fallo más silencioso en esta página. Nada reporta un problema hasta que el bucle del agente hace su primera solicitud de modelo y recibe un error de autenticación o cuota. Confirma la facturación y el acceso al modelo antes de culpar al código. Una vez perdí una mañana porque culpé al código primero.

Abre e instala el proyecto

Abre una terminal en la carpeta extraída que contiene package.json, luego instala los paquetes:

$ cd path-to-your-downloaded-project
$ npm install

JunoAbre e instala el proyecto Abre la carpeta extraída que contiene package.json y ejecuta npm install allí. Todos los comandos posteriores en esta página ocurren en esa misma carpeta. Mantener una terminal abierta en esa carpeta te ahorra de perder la pista de dónde estás, cosa que me pasaba constantemente en mi primer mes.

JunoAbre e instala el proyecto Los tres hitos comparten la configuración npm y Vite, así que este paso de instalación es idéntico sin importar cuál extraigas. Instala junto a package.json, luego realiza los dos cambios de código descritos en la siguiente sección. Todos los comandos se ejecutan en esa misma carpeta.

JunoAbre e instala el proyecto Estas exportaciones se envían sin un archivo de bloqueo, el package-lock.json que fija versiones exactas, así que npm install resuelve el SDK de OpenAI y Vite de nuevo en tu máquina. Son posibles diferentes versiones resueltas pero rara vez son la causa aquí. Cuando algo se rompe después, verifica tus ediciones en la fuente antes de empezar a cambiar versiones de paquetes.

Actualiza la clave y el modelo

En index.js, cambia:

apiKey: process.env.OPENAI_API_KEY,

a:

apiKey: import.meta.env.VITE_OPENAI_API_KEY,

Vite lee valores de entorno a través de import.meta.env; la misma reparación aparece en Ejecutar Embeddings y Vector Databases localmente, que adapta una exportación de curso similar.

Las instantáneas del curso usan IDs de modelo antiguos como gpt-3.5-turbo, gpt-3.5-turbo-1106 y gpt-4-1106-preview. Para estos ejemplos del curso, reemplaza el valor del modelo en tu index.js extraído con gpt-4o-mini:

model: "gpt-4o-mini",

Crea .env junto a package.json:

VITE_OPENAI_API_KEY=your-openai-api-key

Crea .gitignore en la misma carpeta:

.env
node_modules/

El .gitignore mantiene tu clave fuera de cualquier repositorio que crees desde esta carpeta; ignorar archivos y buenas prácticas explica por qué eso importa.

Esta configuración de aprendizaje expone la clave

El SDK de OpenAI se ejecuta intencionalmente en el navegador, y Vite coloca la clave en el bundle del frontend. Usa solo una clave temporal y restringida. No despliegues ni compartas esta versión. Los agentes en producción necesitan un backend.

JunoActualiza la clave y el modelo Intercambia la búsqueda de clave antigua y el nombre del modelo en index.js, pon tu clave temporal en .env, y mantén ese archivo fuera de Git. Esta versión de aprendizaje expone la clave al navegador a propósito, así que usa una clave que puedas cancelar en el momento en que termines este proyecto. Nunca uses una clave de la que algo más dependa.

JunoActualiza la clave y el modelo Vite solo expone variables que comienzan con VITE_, así que el nombre en la fuente y el nombre en .env deben coincidir exactamente. Busca también en toda la descarga IDs de modelo antiguos, porque diferentes hitos contienen diferentes instantáneas. Si te pierdes un ID, un hito funcionará mientras que otro falla.

JunoActualiza la clave y el modelo La solución en producción es arquitectónica: crea el cliente de OpenAI en un backend y haz que el navegador llame a ese backend, para que la clave nunca abandone el servidor. La sustitución de Vite aquí pertenece al modo de aprendizaje, y no es el patrón para desplegar. Agregar un backend después del lanzamiento cuesta más que construirlo primero, y lo he hecho en ambos órdenes.

Ejecuta el proyecto

$ npm start

Abre la URL exacta Local impresa por Vite. Para un hito solo de consola, abre las herramientas de desarrollador de tu navegador y selecciona Console. Los bucles ReAct y function imprimen su progreso y respuesta allí. En el hito de interfaz de usuario, envía un mensaje y busca la respuesta en la página. Detén Vite con Ctrl+C.

JunoEjecuta el proyecto Ejecuta npm start y abre la URL Local exacta que Vite imprime. Para los hitos anteriores, la salida aparece en la Consola del navegador, así que una página que se vea vacía puede estar funcionando correctamente. Presiona Ctrl+C para detener cuando termines.

JunoEjecuta el proyecto Vite elige el puerto e imprime la dirección exacta, así que usa lo que imprime en lugar de una URL recordada. En un hito de solo consola, una página en blanco es lo que deberías esperar; verifica la Consola del desarrollador para la salida del bucle antes de tratarlo como un fallo de inicio. Solo el hito de interfaz de usuario responde en la página en sí.

JunoEjecuta el proyecto Vite iniciando prueba que el proyecto editado se compila, y nada más; OpenAI aún no ha sido contactado. Ejecuta una interacción real, ya sea la salida del bucle en DevTools o un mensaje a través de la interfaz final, antes de decidir que la configuración está terminada. Un proyecto que se compila no es un proyecto que funciona, y dejé de aceptar esa conclusión hace años.

Solución de problemas

process is not defined: Busca en index.js el process.env.OPENAI_API_KEY restante y reemplázalo con la forma de Vite anterior.

Un modelo antiguo no está disponible: Confirma que todos los campos model usan un modelo actual disponible para tu proyecto de OpenAI. Los hitos descargados pueden contener diferentes IDs antiguos.

La página se ve vacía: Los hitos anteriores reportan progreso en la consola del desarrollador en lugar de la página. Usa la lección de interfaz de usuario final si quieres una interfaz de chat visible.

Error de autenticación o cuota: Verifica que .env esté junto a package.json, reinicia Vite y confirma la facturación y el acceso a claves en la cuenta de OpenAI.

JunoSolución de problemas Coincide cada síntoma con su solución: process is not defined significa que la búsqueda de clave aún necesita cambiar, una página vacía generalmente significa que la salida está en la Consola, y un error de autenticación apunta a la clave o a la cuenta. Cada uno tiene una única solución. Trabaja a través de ellos con calma, uno a la vez.

JunoSolución de problemas Verifica en orden: la fuente lee la variable de Vite, .env usa el nombre coincidente, todos los IDs de modelo son actuales y estás observando el lugar donde ese hito realmente imprime su salida. Esa secuencia sigue el orden en el que se construye la solicitud, así que el primer paso que falla es la causa. Soluciona ese y vuelve a ejecutar antes de cambiar cualquier otra cosa.

JunoSolución de problemas Cuando el agente permanece en silencio, hay cuatro posibles causas: la clave nunca llegó al bundle, el ID del modelo ya no existe, OpenAI rechazó la cuenta, o la interfaz de usuario descartó el mensaje devuelto. Verifica en ese orden, porque un fallo temprano en la lista produce los mismos síntomas que los posteriores. Verificarlos fuera de orden una vez convirtió una solución de cinco minutos en toda una tarde para mí.