07 Evaluar un cambio

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

Punto de partida

git checkout checkpoint/07-evaluation

Tu aplicación tiene tracing, monitorización, un dataset alojado y al menos una ejecución de experimento con puntuaciones keyword_overlap y correctness. Ahora vas a cambiar la aplicación y repetir el experimento para saber si mejoró o empeoró.

Observa la primera ejecución antes de cambiar nada. Abre dataset → Runs y revisa los promedios:

• promedio de correctness: ¿qué fracción de elementos consideró realmente correcta el juez?
• promedio de keyword_overlap: ¿qué fracción cubrió los pasos esperados?

Abre los elementos donde alguna puntuación sea baja y lee la respuesta del agente. Es habitual descubrir que omitió un paso, rechazó algo que sí debía atender o dio consejos genéricos en lugar de instrucciones específicas para iPhone. Lo que encuentres es el problema que intentarás resolver.

Por qué evaluar cambios con experimentos

Si cambias cualquier parte de tu aplicación de IA —prompt, modelo, contexto o arquitectura del agente— necesitas saber si el sistema mejoró de verdad. Revisar una o dos salidas parece convincente, pero no generaliza. Volver a ejecutar el mismo dataset con la nueva versión y comparar las puntuaciones con la ejecución anterior es lo más parecido a una medición.

Esto también permite cerrar el ciclo y publicar con confianza: cuando suben los promedios de la nueva ejecución —y lees suficientes elementos para confirmar que la puntuación refleja la realidad— tienes evidencia para desplegar el cambio.

Qué puedes cambiar

Este capítulo se centra en iterar el prompt porque es la opción con menos fricción. El mismo flujo sirve si cambias:

• El modelo — prueba uno más potente o barato y vuelve a ejecutar.
• El contexto — añade o elimina campos del prompt de sistema o de los resultados de herramientas.
• La arquitectura del agente — añade una herramienta, cambia el orden o los reintentos.
• El prompt — lo que haremos aquí.

La forma siempre es la misma: cambia una cosa —o una configuración de variables—, vuelve a ejecutar el dataset y compara en paralelo.

Objetivo

Cambiar algo del prompt y mejorar los resultados, medidos por el aumento de correctness y keyword_overlap en el dataset.

Tres pasos:

1. Cambiar una cosa — sustituir la variante del prompt o editarla en Langfuse.
2. Volver a ejecutar el dataset con el nuevo prompt.
3. Comparar las ejecuciones en paralelo y decidir si publicarlo.

Paso 1 — Cambiar el prompt

El cambio debe responder a lo que observaste en la ejecución 1; por ejemplo, elementos con correctness baja porque el agente evitó una solicitud fuera de alcance en vez de rechazarla con claridad. Una edición concreta sería:

Añade una regla: "Si una solicitud queda fuera de la ayuda con iPhone —impuestos, reservas de viaje o cualquier cosa que necesite acceso en directo a una cuenta— dilo de forma directa en una sola frase: con qué no puedes ayudar y con qué sí. Después, detente. No intentes responder a la solicitud."

Así el comportamiento fuera de alcance queda explícito en lugar de dejar que el modelo improvise.

Dos formas de aplicar el cambio:

Opción A — En Langfuse (crear una versión nueva desde la interfaz, recomendada):

Prompts → dad-it-support-agent → crea una versión o draft → añade la regla a Rules → guarda la versión → promociónala al label production. El resolver recupera por label, así que la siguiente solicitud usa la versión nueva automáticamente. Este es el flujo que utilizará tu equipo para iterar continuamente en producción.

Opción B — En el código (editar src/server/support-agent.ts y volver a publicar):

Abre src/server/support-agent.ts, añade la misma regla al bloque Rules de la constante SYSTEM_PROMPT y publica:

npm run prompt:publish

El repositorio también incluye una variante gentler lista (WORKSHOP_PROMPT_VARIANT=gentler npm run prompt:publish), útil si solo quieres observar cualquier cambio de prompt en vez de diseñar uno.

En ambos casos acabas con una versión nueva, que utilizará la siguiente llamada a runSupportConversation(...).

Paso 2 — Volver a ejecutar el dataset

npm run dataset:run

Ahora tienes dos ejecuciones en el mismo dataset, cada una vinculada a una versión diferente del prompt. El evaluador keyword_overlap del script y el evaluador correctness del paso 06 puntúan automáticamente la nueva ejecución.

Paso 3 — Comparar

En Langfuse:

• Dataset → pestaña Runs → dos filas con promedios de keyword_overlap y correctness.
• Chart view → promedios de cada ejecución en paralelo.
• Añade la ejecución nueva como 'Compare with' en la barra lateral.

Observa:

• Qué elementos mejoraron intencionadamente.
• Cuáles empeoraron: la parte que hace útil la evaluación.
• Si el cambio alteró el alcance: ¿más rechazos, respuestas más seguras, más pasos por respuesta?

Cómo verificar que has terminado

• Aparecen dos ejecuciones en el dataset, vinculadas a versiones distintas del prompt.
• Las dos puntuaciones (keyword_overlap, correctness) tienen promedios que puedes comparar.
• Si una puntuación sigue pendiente, actualiza después de que termine la cola del evaluador.

Cierre

Cerrar el ciclo —cambiar → volver a ejecutar → comparar → decidir— convierte los cambios de prompt o modelo de decisiones intuitivas en decisiones de ingeniería. Cada cambio futuro obtiene una línea base gratuita.

La skill de Langfuse (/langfuse) incrementa versiones de prompts, vincula ejecuciones con versiones y genera automáticamente un gráfico comparativo. Este recorrido existe para mostrar lo que hace por debajo.

Estado final

Este es el punto de partida para 08-wrap-up.