00 Configuración

Deja la aplicación del workshop ejecutándose localmente con las credenciales de OpenAI y Langfuse. Después puedes recorrer 01-base-app y empezar a construir en 02-tracing.

El material del workshop se mantiene en el repositorio público langfuse/langfuse-workshop. Usa el repositorio para ejecutar la aplicación, acceder a las ramas de checkpoint y realizar la configuración local.

Ver este archivo Markdown

Objetivo

Deja la aplicación del workshop ejecutándose localmente con las credenciales de OpenAI y Langfuse. Después puedes recorrer 01-base-app y empezar a construir en 02-tracing.

Requisitos previos

Node.js ^20.19.0 || >=22.12.0 — comprueba la versión con node -v y actualiza antes de instalar si es inferior (nvm install 22 o el equivalente para asdf, fnm o volta).

Una versión antigua falla de una forma fácil de malinterpretar. El binario de Vite específico de la plataforma es una dependencia opcional, así que npm lo omite sin informar de ningún error: npm install parece correcto y el problema solo aparece después, cuando npm run dev no puede iniciar Vite. Si actualizas Node tras instalar, ejecuta de nuevo npm ci para descargar el binario omitido.

Punto de partida

Clona el repositorio del workshop, entra en él y haz checkout del checkpoint de configuración para este capítulo:

git clone https://github.com/langfuse/langfuse-workshop.git
cd langfuse-workshop
git checkout checkpoint/00-setup

Este checkpoint contiene intencionadamente la misma aplicación base sin tracing que checkpoint/01-base-app. Úsalo para confirmar las claves de API, las dependencias y los puertos locales antes de pasar a los capítulos de construcción. Las claves de Langfuse se configuran ahora, pero los traces solo comienzan después de añadir la instrumentación en 02-tracing.

Paso 1 — Obtener las claves de API

OpenAI — ve a platform.openai.com → API Keys → crea una. Copia el valor sk-....
Langfuse — regístrate en langfuse.com en la región EU, crea un proyecto y copia las claves pública y secreta desde Settings → API Keys.

Paso 2 — Instalar la skill y la CLI de Langfuse

Los módulos posteriores controlan Langfuse mediante un agente de programación, que necesita la skill langfuse y la CLI de Langfuse.

Pega esta instrucción en tu agente para instalar ambas:

"Instala la skill langfuse desde https://github.com/langfuse/skills/tree/main/skills/langfuse e instala la CLI de Langfuse con npm install -g langfuse-cli."

Si prefieres instalarlas tú:

# Langfuse CLI
npm install -g langfuse-cli

# Langfuse Skill:
npx skills add langfuse/skills --skill "langfuse"

Paso 3 — Configurar `.env`

cp .env.example .env

Completa:

OPENAI_API_KEY=sk-...
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

Deja el resto de valores predeterminados como están.

La aplicación siempre carga el archivo .env de este repositorio para el servidor y los scripts auxiliares. Los valores LANGFUSE_*, OPENAI_* o DATASET_NAME exportados en el shell por otro proyecto no sustituyen este archivo. Para cambiar la configuración del workshop, edita .env.

Conserva estos valores solo en tu .env local. No pegues claves reales de API en notas, transcripciones, capturas de pantalla o chats compartidos.

Paso 4 — Instalar y ejecutar

npm install
npm run dev

Abre http://127.0.0.1:3333.

Para comprobar el servidor por separado, visita http://127.0.0.1:8787/api/health o http://127.0.0.1:8787/api/support-context. Durante npm run dev, 127.0.0.1:8787/ no es la URL principal de la aplicación.

Si no carga nada en 127.0.0.1:3333, retrocede en la salida de npm run dev hasta las líneas [dev:client]. concurrently mantiene la API activa aunque Vite se haya cerrado, por lo que el terminal parece seguir vivo; abrir 127.0.0.1:8787/ en ese estado responde con ENOENT ... dist/index.html, que solo indica que falta el build de producción y no explica el fallo real. Un error Cannot find native binding en esas líneas [dev:client] indica la versión de Node; consulta los Requisitos previos.

Paso 5 — Confirmar lo que ves

Deberías ver el chat Dad IT Support Agent:

la mascota Specs en la parte superior
un saludo de Specs
sugerencias debajo del saludo
el panel del iPhone a la derecha ("Dad" + detalles del iPhone 15)

Cómo atiende Specs una solicitud: un agente, dos herramientas, un modelo y cada salto como observación del trace.

Cómo verificar que has terminado

npm run dev está ejecutándose y escucha en http://127.0.0.1:3333 (cliente) y http://127.0.0.1:8787 (servidor de API).
http://127.0.0.1:8787/api/health o http://127.0.0.1:8787/api/support-context devuelve una respuesta real.
El navegador muestra el saludo de Specs, no un error.
Enviar una sugerencia devuelve una respuesta real del modelo sobre el iPhone.

Estado final

Tu entorno está listo. Para construir el workshop paso a paso, recorre 01-base-app si quieres conocer la aplicación y después haz checkout de checkpoint/02-tracing para los primeros cambios de código.