Observabilidad de agentes de IA: Langfuse, OpenTelemetry, trazas y errores
Tutorial en español para observar agentes de IA con Langfuse y OpenTelemetry: trazas, spans, tools, RAG, latencia, coste, errores, privacidad y evals.
Resumen rápido
Tutorial en español para observar agentes de IA con Langfuse y OpenTelemetry: trazas, spans, tools, RAG, latencia, coste, errores, privacidad y evals. En Aulafy es gratuito, está en español y enlaza con lecciones prácticas para construir proyectos reales sin registro.
Para quién es
Para desarrolladores, equipos de datos, makers técnicos y pymes que ya tienen un chatbot, un RAG, un workflow n8n o un agente con tools y necesitan saber por qué responde mal, tarda demasiado, cuesta más de lo previsto o ejecuta pasos que nadie puede reconstruir.
Qué conseguirás
Aprenderás a pasar de logs sueltos a trazas útiles: cada ejecución tendrá entrada, pasos, llamadas a herramientas, contexto recuperado, modelo, latencia, coste, errores, aprobación humana y resultado. El objetivo no es vigilarlo todo: es guardar la evidencia mínima para depurar sin convertir las trazas en una fuga de datos.
Por qué observar un agente es distinto a observar una API normal
Una API tradicional suele recibir una entrada, ejecutar código y devolver una salida. Un agente de IA puede decidir varios pasos, llamar tools, consultar documentos, reintentar, resumir memoria, cambiar de modelo o pedir aprobación humana. Si solo guardas el error final, no sabrás si falló el prompt, el modelo, la herramienta, el chunk recuperado, el permiso o el criterio de parada.
- Una traza agrupa toda la ejecución de una petición o tarea.
- Un span representa un paso: llamada al modelo, búsqueda RAG, tool, validación o aprobación.
- Los eventos registran hechos puntuales: retry, timeout, bloqueo por política o feedback humano.
- Las métricas ayudan a ver tendencias: latencia, coste, tokens, errores repetidos y tasa de abstención.
Modelo mental: trace, span, generation y score
OpenTelemetry aporta el lenguaje común de observabilidad: trazas, spans, logs, métricas y propagación de contexto. Langfuse lo adapta al mundo LLM: entiende generations, uso de tokens, coste, prompts, datasets, experimentos y evaluaciones. La combinación sana es usar OTel como base interoperable y Langfuse como capa específica para aplicaciones de IA.
- Trace: una pregunta del usuario, un ticket procesado o una tarea completa.
- Span: retrieve_docs, call_model, run_tool, validate_answer o human_review.
- Generation: llamada concreta a un modelo con parámetros, uso y salida.
- Score: evaluación automática o humana sobre grounding, utilidad, seguridad o formato.
Tutorial paso a paso
Empieza con una sola ruta crítica. No intentes instrumentar todo el producto el primer día. Elige una tarea real, por ejemplo: usuario pregunta, el agente busca en Qdrant, genera una respuesta, valida citas y crea un borrador pendiente de aprobación. Instrumenta esa cadena de principio a fin.
- Paso 1: define un request_id y conserva el mismo identificador en todo el recorrido.
- Paso 2: crea una traza por tarea, no una traza nueva por cada función interna.
- Paso 3: registra spans para retrieval, modelo, tools, validación y aprobación humana.
- Paso 4: guarda entradas y salidas resumidas; evita volcar datos personales completos.
- Paso 5: añade scores: respuesta con cita correcta, tool exitosa, riesgo detectado, coste aceptable.
- Paso 6: revisa tres ejecuciones malas y comprueba si puedes explicar la causa solo con la traza.
Ejemplo mínimo de traza para un agente con RAG
Un buen esquema cabe en pocas líneas. La clave es que cada campo responda a una pregunta de depuración: qué pasó, dónde pasó, cuánto tardó, qué datos usó, qué decidió y qué evidencia queda para revisarlo.
- trace: support-1042, usuario anonimizado, entorno, versión del prompt y modelo elegido.
- span retrieve_docs: colección, filtros, número de chunks, ids de fuente y latencia.
- span call_model: proveedor o runtime, modelo, tokens aproximados, coste y temperatura.
- span validate_answer: citas presentes, formato válido, abstención o riesgo detectado.
- span human_review: aprobado, editado, rechazado o escalado.
Privacidad: lo que no debes guardar por defecto
La observabilidad puede convertirse en el sitio donde se filtra todo: prompts con datos personales, documentos completos, secretos pegados por error o respuestas sensibles. Por eso hay que diseñar una política antes de encender trazas en producción.
- No guardes claves, tokens, .env ni cabeceras Authorization.
- No guardes documentos completos si bastan ids, hashes, página y fragmento mínimo.
- Separa trazas de desarrollo, preview y producción.
- Define retención: cuánto tiempo se conservan trazas y quién puede leerlas.
- En datos personales o regulados, valida base legal, finalidad, acceso y borrado.
Checklist de producción
Antes de decir que un agente está listo, debe poder explicar sus propios fallos. Esta checklist convierte la observabilidad en una puerta de calidad, no en un panel bonito que nadie mira.
- Puedo reconstruir una respuesta mala sin preguntar al usuario qué pasó.
- Puedo distinguir fallo de retrieval, fallo de modelo, fallo de tool y fallo de permisos.
- Puedo ver coste, latencia y tokens por tarea o por cliente.
- Puedo detectar loops, retries repetidos y herramientas llamadas demasiadas veces.
- Puedo enlazar una versión de prompt o política con cada ejecución.
- Puedo borrar o anonimizar trazas según la política de datos.
Fuentes oficiales para seguir aprendiendo
La base técnica debe contrastarse con documentación primaria. Langfuse documenta observabilidad LLM, tracing y OpenTelemetry; OpenTelemetry documenta los conceptos generales de trazas, spans, propagación de contexto, logs y métricas.
- Langfuse observability overview: https://langfuse.com/docs/observability/overview
- Langfuse tracing get started: https://langfuse.com/docs/observability/get-started
- Langfuse OpenTelemetry integration: https://langfuse.com/integrations/native/opentelemetry
- OpenTelemetry traces: https://opentelemetry.io/docs/concepts/signals/traces/
- OpenTelemetry observability primer: https://opentelemetry.io/docs/concepts/observability-primer/
Preguntas frecuentes
¿Qué diferencia hay entre logs y trazas?
Un log registra un hecho aislado. Una traza une todos los pasos de una ejecución y permite ver la relación entre entrada, spans, tools, modelo, errores y resultado.
¿Langfuse sustituye a OpenTelemetry?
No. Langfuse usa y se integra con OpenTelemetry, pero aporta una capa específica para LLMs: generations, prompts, tokens, coste, datasets, experimentos y scores.
¿Qué registro siempre en un agente?
Request id, modelo, versión del prompt, tools llamadas, argumentos resumidos, chunks usados, latencia, coste aproximado, errores, aprobación humana y resultado.
¿Debo guardar prompts completos?
Solo si la finalidad, privacidad y permisos lo permiten. En muchos casos basta con ids, hashes, extractos mínimos y referencias a documentos.
¿Sirve para agentes locales con Ollama?
Sí. Local no significa invisible: también necesitas trazas para medir latencia, uso de GPU, cola, errores de tools, recuperación RAG y calidad de respuestas.
¿Cuándo está listo para producción?
Cuando puedes reconstruir fallos importantes desde la traza, limitar datos sensibles, medir coste y latencia, comparar versiones y detectar loops o respuestas sin evidencia.