Langfuse es una plataforma de código abierto que registra todo lo que hace tu agente de IA (cada llamada al modelo, su coste, su latencia y su resultado) para que puedas depurarlo y evaluarlo con datos, no a ciegas. Lo mejor es que puedes autoalojarla entera con Docker Compose y que tus trazas nunca salgan de tu servidor. En esta guía verás qué es Langfuse, cómo desplegarla, qué modelo de datos usa (trazas, spans y generaciones), cómo instrumentar un agente con OpenTelemetry y cómo montar evaluaciones con datasets. La misma explicación está disponible en inglés.

Puntos clave

  • Langfuse es una plataforma de ingeniería de LLM de código abierto (licencia MIT, salvo la carpeta ee/ de funciones empresariales); supera las 31 300 estrellas en GitHub y su rama estable es la v3, con una versión nueva casi a diario (la última, la v3.218.0, del 16 de julio de 2026).
  • Es autoalojable: un docker compose up levanta la interfaz web en el puerto 3000 con cuatro almacenes detrás, así que tus trazas se quedan en tu infraestructura.
  • Su modelo de datos son las trazas, que agrupan observaciones de tipo span (una unidad de trabajo) y generación (una llamada al modelo, con sus tokens, coste y latencia).
  • Instrumentar un agente es cuestión de un decorador: el SDK de Python v3 está construido sobre OpenTelemetry, el estándar abierto de trazabilidad, y trae integraciones directas con OpenAI, LangChain, LiteLLM y LlamaIndex.
  • Va más allá del registro: gestiona prompts, guarda datasets de prueba y ejecuta evaluaciones (incluido el juez LLM) para comparar versiones de tu agente con métricas objetivas.

¿Qué es Langfuse?

Langfuse es una plataforma de observabilidad y evaluación para aplicaciones que usan modelos de lenguaje. Su propia documentación la define como «una plataforma de ingeniería de LLM de código abierto»: va más allá de las métricas de sistema como la CPU o la memoria y entiende los conceptos propios de un agente de IA, es decir, los prompts, las respuestas del modelo, los tokens consumidos, el coste en dólares y las herramientas que invoca.

El problema que resuelve es concreto. Cuando un agente construido con el SDK de Anthropic o un grafo de LangGraph se comporta mal, un print en la consola no te sirve de nada: no ves qué prompt exacto recibió el modelo, cuántas iteraciones dio el bucle ni cuánto te costó cada intento. Langfuse graba ese árbol de ejecución completo y te lo muestra en una línea de tiempo navegable.

El proyecto nació en la aceleradora Y Combinator (promoción de invierno de 2023) y se ha convertido en uno de los referentes del sector: reúne más de 31 300 estrellas en GitHub. Su código es libre bajo licencia MIT, con la única excepción de la carpeta ee/, que agrupa funciones empresariales sujetas a una clave de licencia. Todo lo que necesitas para observar y evaluar agentes está en la parte abierta.

Desplegarlo con Docker Compose

La gran ventaja de Langfuse frente a un servicio en la nube es que puedes ejecutarlo entero en tu propia máquina, así que ni los prompts ni las respuestas de tus usuarios abandonan tu red. El arranque es el clásico de tres órdenes:

git clone https://github.com/langfuse/langfuse.git
cd langfuse

    # Levanta la interfaz web en http://localhost:3000
docker compose up -d

Detrás de esa única orden se levantan cuatro almacenes, cada uno con su cometido: Postgres guarda los datos transaccionales (usuarios, proyectos, prompts); ClickHouse es la base de datos analítica que absorbe el gran volumen de trazas; Redis hace de caché y de cola de eventos; y un almacenamiento compatible con S3 (por defecto, un contenedor de MinIO) retiene los eventos en bruto y los adjuntos. Esa separación es la que permite a Langfuse ingerir millones de trazas sin ahogarse.

El docker compose que trae el repositorio está pensado para pruebas y despliegues pequeños: no incluye alta disponibilidad ni escalado horizontal automático (para eso está el chart de Kubernetes). Antes de exponerlo en producción, cambia todos los secretos marcados con # CHANGEME en el docker-compose.yml, en especial NEXTAUTH_SECRET, SALT, ENCRYPTION_KEY y las contraseñas de las bases de datos. Con el contenedor arriba, abre http://localhost:3000, crea la primera cuenta y un proyecto, y anota el par de claves de API (pk-lf-… y sk-lf-…) que usarás para enviar trazas.

Trazas, spans y generaciones

Para sacar partido a Langfuse conviene tener claro su modelo de datos, que es deliberadamente sencillo. La pieza raíz es la traza (trace): representa una petición completa de principio a fin, por ejemplo «el usuario preguntó X y el agente respondió Y». Dentro de una traza cuelgan las observaciones, y hay tres tipos:

  • Span: una unidad de trabajo con duración, como un paso de recuperación en una base de datos vectorial o la ejecución de una herramienta. Los spans se anidan y forman el árbol de la ejecución.
  • Generación (generation): un tipo especial de span para las llamadas al modelo. Captura el modelo usado, el prompt de entrada, la respuesta, los tokens de entrada y salida, el coste calculado y la latencia.
  • Evento (event): un punto concreto en el tiempo, sin duración, para marcar hitos.

Por encima de las trazas, las sesiones agrupan varias trazas de una misma conversación, y las puntuaciones (scores) adjuntan a cualquier traza un valor de calidad, numérico, categórico o booleano, que puede venir de un usuario, de una regla o de un modelo juez. Con esas cuatro piezas (trazas, observaciones, sesiones y puntuaciones) se describe cualquier aplicación de IA, desde un chatbot simple hasta un sistema multiagente al estilo de CrewAI.

Instrumentar un agente con OpenTelemetry

Aquí es donde Langfuse brilla por su pragmatismo. El SDK de Python v3 está construido sobre OpenTelemetry, el estándar abierto de la industria para la trazabilidad, de modo que no te ata a un formato propietario. Instalarlo es una sola orden:

pip install langfuse

La forma más rápida de instrumentar código es el decorador @observe(): envuelve cualquier función y Langfuse crea automáticamente un span con sus argumentos de entrada y su valor de retorno. Para las llamadas al modelo hay un atajo aún mejor: importar el cliente de OpenAI desde langfuse.openai convierte cada petición en una generación completa sin tocar nada más.

from langfuse import observe
from langfuse.openai import openai  # cliente de OpenAI ya instrumentado

@observe()
def responder(pregunta: str) -> str:
    # Esta llamada se registra sola como una generacion,
    # con modelo, tokens, coste y latencia incluidos.
    respuesta = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": pregunta}],
    )
    return respuesta.choices[0].message.content

responder("Resume que es la observabilidad de agentes")

Configura las tres variables de entorno LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY y LANGFUSE_HOST (apuntando a tu http://localhost:3000) y, en cuanto ejecutes la función, verás la traza aparecer en la interfaz. Como el SDK se apoya en OpenTelemetry, cualquier biblioteca ya instrumentada con ese estándar exporta sus spans a Langfuse sin código extra, y existen integraciones directas para LangChain, LiteLLM y LlamaIndex.

Evaluaciones y datasets

Observar es el primer paso; el segundo es medir si tu agente mejora o empeora cuando cambias un prompt o un modelo. Langfuse resuelve esto con dos herramientas que trabajan juntas. Un dataset es una colección de casos de prueba, cada uno con una entrada y, opcionalmente, la salida esperada; puedes crearlo a mano o promover a él las trazas reales que más te interesen desde la interfaz.

Sobre ese dataset ejecutas un experimento: corres tu agente contra cada caso y Langfuse guarda cada resultado como una traza enlazada al dataset. Después aplicas evaluadores que asignan puntuaciones: pueden ser comprobaciones deterministas (¿la respuesta contiene la cifra correcta?) o un juez LLM, es decir, otro modelo al que le pides que valore la corrección o el tono con una rúbrica. La interfaz compara dos ejecuciones lado a lado, así que ves de un vistazo si la versión nueva del prompt sube o baja la puntuación media. Es el mismo rigor que aplicarías al servir un modelo con vLLM en producción, pero aplicado a la calidad de las respuestas en lugar de al rendimiento del servidor.

Preguntas frecuentes

¿Es Langfuse realmente gratis y de código abierto?

Sí. El grueso de Langfuse, incluida toda la observabilidad, la gestión de prompts, los datasets y las evaluaciones, es software libre bajo licencia MIT, y puedes autoalojarlo sin pagar nada. La única excepción es la carpeta ee/ del repositorio, que agrupa funciones empresariales (como el inicio de sesión único empresarial o permisos avanzados) sujetas a una clave de licencia de pago. Para observar y evaluar agentes no la necesitas.

¿Qué diferencia hay entre Langfuse y OpenTelemetry?

OpenTelemetry es un estándar abierto y un conjunto de bibliotecas para generar y transportar trazas, pero no incluye almacenamiento ni interfaz. Langfuse usa OpenTelemetry como base de su SDK y añade lo que falta: una base de datos especializada (ClickHouse), una interfaz para explorar las trazas y las capas de evaluación y gestión de prompts. En resumen, OpenTelemetry produce las trazas y Langfuse las recibe, las guarda y te deja trabajar con ellas.

¿Puedo usar Langfuse con modelos locales?

Sí. Como el SDK instrumenta tu código, no el proveedor, funciona con cualquier modelo, incluidos los que ejecutas en tu propia máquina con Ollama a través de su API compatible con OpenAI. Autoalojando Langfuse y sirviendo el modelo de forma local consigues una plataforma de agentes completa en la que ningún dato sale de tu red, algo clave en entornos con requisitos estrictos de privacidad.

Conclusión

Langfuse cubre el hueco entre «mi agente funciona en mi portátil» y «mi agente funciona en producción y sé por qué». Con un docker compose up tienes una plataforma de observabilidad completa que graba cada traza, span y generación, calcula el coste y la latencia de cada llamada, y te deja evaluar cambios con datasets y un juez LLM, todo dentro de tu propia red y con licencia MIT. El siguiente paso es clonar el repositorio, levantar el contenedor, instalar el SDK con pip install langfuse y añadir un @observe() a la primera función de tu agente para ver aparecer tu primera traza.

Fuentes: [1] Documentación oficial de Langfuse[1], [2] Langfuse en GitHub[2], [3] Paquete langfuse en PyPI[3], [4] OpenTelemetry, el estándar de trazabilidad[4].

Visitas: 0

Fuentes

  1. Documentación oficial de Langfuse
  2. Langfuse en GitHub
  3. Paquete langfuse en PyPI
  4. OpenTelemetry, el estándar de trazabilidad

Ruta: Agentes de IA en producción: evaluación y fiabilidad