¡Hola a todos, Leo aquí de agntdev.com. ¡Espero que todos estén teniendo una semana productiva!
Hoy, quiero profundizar en algo que ha estado en mi mente últimamente, especialmente mientras he estado experimentando con algunos proyectos personales que involucran flujos de trabajo agenticos más complejos y de múltiples pasos. Hablamos mucho sobre construir agentes, sobre los LLMs en sí mismos, y sobre las cosas geniales que pueden hacer. Pero, ¿qué pasa con el aspecto menos glamouroso, pero absolutamente crucial, de asegurarnos de que nuestros agentes realmente funcionen de manera confiable y eficiente a lo largo del tiempo?
Específicamente, estoy hablando sobre la observabilidad de los agentes. No se trata solo de registrar información; se trata de entender verdaderamente lo que está haciendo tu agente, por qué lo está haciendo y detectar problemas antes de que se conviertan en una bola de nieve. En un mundo donde los agentes están interactuando con APIs externas, tomando decisiones basadas en entradas dinámicas, y potencialmente funcionando durante períodos prolongados, volar a ciegas es una receta para el desastre. Aprendí esto por las malas, como explicaré.
El “Error Misterioso” Que Me Enseñó Todo
Hace unos meses, estaba desarrollando un agente asistente personal. Llamémoslo “Proyecto Chronos.” Su trabajo era monitorear mi calendario, fuentes de noticias y canales específicos de Slack, luego sugerir proactivamente horarios de reuniones, resumir actualizaciones clave o incluso redactar respuestas iniciales a preguntas comunes. Cosas bastante estándar en la superficie.
Lo construí, lo probé con algunos escenarios, y parecía funcionar bien. Lo configuré para que funcionara durante la noche, pensando que me despertaría con un resumen perfectamente curado. En su lugar, me desperté con… nada. O más bien, un resumen parcial que terminó abruptamente, seguido de un mensaje de error críptico en mis registros del sistema que esencialmente decía “algo se rompió.”
Depurar esto fue una pesadilla. Chronos debía hacer varias cosas: obtener eventos del calendario, consultar una API de noticias, acceder a una API de Slack, procesar los datos y luego generar un resumen. ¿Qué paso falló? ¿Por qué? ¿Acaso intentó todos los pasos? ¿Fue un límite de tasa de API? ¿Un prompt malformado? ¿Un tiempo de espera? No tenía idea.
Mis registros iniciales eran básicos: “Iniciado paso X,” “Paso Y completado,” y luego la salida final o un error. Esto no fue suficiente. Era como intentar diagnosticar un problema de automóvil solo sabiendo que arrancó y luego se detuvo, sin ninguna información sobre la temperatura del motor, presión de combustible, o fallos eléctricos.
Esa experiencia me dejó claro el punto: si eres serio acerca del desarrollo de agentes, necesitas observabilidad desde el primer día. No es un pensamiento posterior; es un componente fundamental.
Más allá del Registro Básico: ¿Qué Significa “Observabilidad” para los Agentes?
Para mí, la observabilidad de los agentes se desglosa en algunas áreas clave, cada una proporcionando una perspectiva diferente de la operación de tu agente:
1. Trazado de Ejecución Paso a Paso
Esto es lo más crítico. Necesitas saber exactamente qué está haciendo tu agente en cada etapa de su ejecución. Piénsalo como una detallada pista de migas de pan. Para el Proyecto Chronos, necesitaba ver:
- Cuándo comenzó a obtener eventos del calendario.
- Los parámetros que utilizó para la llamada a la API del calendario (por ejemplo, rango de fechas).
- La respuesta cruda de la API del calendario.
- Cómo procesó esa respuesta.
- El prompt exacto que le envió al LLM para resumir la información del calendario.
- La respuesta del LLM.
- Cualquier herramienta que llamó, con sus entradas y salidas.
- Mensajes de error, no solo “algo falló,” sino un error específico con contexto (por ejemplo, “La API del calendario devolvió 401 No Autorizado para el usuario X”).
Este nivel de detalle es invaluable para recrear problemas y comprender los puntos de decisión. Mis registros iniciales solo indicaban “Obteniendo datos del calendario…” y luego “Resumiendo datos del calendario…” sin nada en medio. No es útil cuando la obtención de datos en sí falla en silencio.
2. Seguimiento de Prompts y Respuestas
El LLM es el cerebro de tu agente. Si no sabes qué prompts está recibiendo y qué respuestas está dando, estás volando a ciegas. Esto incluye:
- El prompt completo enviado al LLM (sistema, usuario y cualquier descripción de llamada de función).
- La temperatura, top_p y otros parámetros de generación.
- La respuesta cruda del LLM, incluyendo cualquier llamada a herramientas que decidió realizar.
- Uso de tokens (entrada, salida, total) para el seguimiento de costos y análisis de rendimiento.
Esto es crucial para la ingeniería de prompts. Si un agente está dando respuestas sin sentido, ver el prompt exacto que recibió te ayuda a depurar si el contexto de entrada estaba mal, o si el prompt en sí estaba mal estructurado.
3. Monitoreo de Llamadas a Herramientas
Los agentes a menudo interactúan con herramientas externas o APIs. Cada interacción es un punto de falla o comportamiento inesperado potencial. Necesitas registrar:
- Qué herramienta fue llamada.
- Los argumentos exactos pasados a la herramienta.
- La salida cruda de la herramienta.
- Cualquier error devuelto por la herramienta o durante su ejecución.
Para Chronos, si intentó llamar a la API de Slack para publicar un resumen, necesitaba saber el canal al que se dirigía, el contenido del mensaje, y si la API devolvía un error 403 Prohibido, por ejemplo. Mi configuración anterior solo me decía “Intentó publicar en Slack.”
4. Instantáneas de Estado
Muchos agentes mantienen algún estado interno: una hoja de notas, una memoria, una lista de hechos que han recopilado. Capturar periódicamente este estado puede ser increíblemente útil para la depuración. Si un agente se queda atrapado en un bucle o toma una mala decisión, ver sus “pensamientos” internos en varios puntos puede revelar dónde se desvió su comprensión.
Esto no se trata tanto de registrar cada cambio de variable y más sobre capturar estados clave de toma de decisiones. Para Chronos, esto podría ser “Comprensión actual del horario del usuario,” o “Principales conclusiones de las fuentes de noticias hasta ahora.”
Enfoques Prácticos: Integrando Observabilidad
Bien, así que, ¿cómo implementamos esto sin ahogarnos en registros? Aquí hay algunas estrategias prácticas y fragmentos de código.
Estrategia 1: Registro Estructurado con Contexto
Olvida las declaraciones `print()`. Usa una biblioteca de registro adecuada (como el módulo `logging` de Python). Crucialmente, enriquece tus mensajes de registro con datos estructurados (JSON, diccionarios) en lugar de solo cadenas simples. Esto hace que los registros sean analizables, buscables y mucho más útiles.
Aquí hay un ejemplo simplificado en Python:
import logging
import json
import uuid
from datetime import datetime
# Configuración básica del logger (en una aplicación real, lo configurarías de manera más completa)
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
formatter = logging.Formatter('%(levelname)s: %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)
def log_agent_step(agent_id: str, step_name: str, status: str, details: dict = None):
log_data = {
"timestamp": datetime.now().isoformat(),
"agent_id": agent_id,
"step_name": step_name,
"status": status, # por ejemplo, "iniciado", "completado", "fallido"
"details": details if details is not None else {}
}
logger.info(json.dumps(log_data))
class MyAgent:
def __init__(self, agent_id: str = None):
self.agent_id = agent_id if agent_id else str(uuid.uuid4())
self.memory = [] # Memoria interna simple
def _fetch_calendar_events(self, user_id: str, date_range: str):
log_agent_step(self.agent_id, "fetch_calendar_events", "iniciado",
{"user_id": user_id, "date_range": date_range})
try:
# Simular llamada a la API
if "error" in date_range:
raise ValueError("Error simulado de API de calendario")
events = [
{"title": "Reunión de Equipo", "time": "10:00 AM"},
{"title": "Reunión con Cliente", "time": "02:00 PM"}
]
log_agent_step(self.agent_id, "fetch_calendar_events", "completado",
{"num_events": len(events), "data_preview": events[0]})
self.memory.append(f"Eventos del calendario: {events}")
return events
except Exception as e:
log_agent_step(self.agent_id, "fetch_calendar_events", "fallido",
{"error": str(e), "traceback": "..."}) # En la vida real, capturar traceback
raise
def _summarize_with_llm(self, prompt_text: str):
log_agent_step(self.agent_id, "summarize_with_llm", "iniciado",
{"prompt_length": len(prompt_text), "prompt_preview": prompt_text[:100]})
try:
# Simular llamada LLM
if "fail_llm" in prompt_text:
raise RuntimeError("Error simulado de API LLM")
response = f"Resumen LLM de: {prompt_text[:50]}..."
token_usage = {"input": len(prompt_text) // 4, "output": len(response) // 4}
log_agent_step(self.agent_id, "summarize_with_llm", "completado",
{"response_length": len(response), "token_usage": token_usage,
"llm_response_preview": response[:100]})
self.memory.append(f"Resumen producido por LLM: {response}")
return response
except Exception as e:
log_agent_step(self.agent_id, "summarize_with_llm", "fallido",
{"error": str(e), "traceback": "..."})
raise
def run_daily_briefing(self, user_id: str):
log_agent_step(self.agent_id, "run_daily_briefing", "iniciado", {"user_id": user_id})
try:
calendar_data = self._fetch_calendar_events(user_id, "hoy")
news_summary = self._summarize_with_llm("Resume las principales noticias de hoy...")
final_briefing_prompt = (
f"Crea un informe diario basado en:\n"
f"Calendario: {json.dumps(calendar_data)}\n"
f"Noticias: {news_summary}"
)
final_briefing = self._summarize_with_llm(final_briefing_prompt)
log_agent_step(self.agent_id, "run_daily_briefing", "completado",
{"final_briefing_length": len(final_briefing)})
return final_briefing
except Exception as e:
log_agent_step(self.agent_id, "run_daily_briefing", "fallido",
{"error": str(e), "current_memory": self.memory}) # Captura de memoria en caso de fallo
raise
# Ejemplo de uso
if __name__ == "__main__":
agent = MyAgent()
print(f"\n--- Ejecutando Agente {agent.agent_id} (Caso de Éxito) ---")
try:
briefing = agent.run_daily_briefing("leo_g")
print(f"Informe: {briefing[:100]}...")
except Exception as e:
print(f"Falló la ejecución del agente: {e}")
agent_fail = MyAgent()
print(f"\n--- Ejecutando Agente {agent_fail.agent_id} (Caso de Fallo de Calendario) ---")
try:
# Simular fallo de calendario pasando "error" en date_range
agent_fail._fetch_calendar_events("leo_g", "error_today")
except Exception as e:
print(f"Falló la ejecución del agente como se esperaba: {e}")
agent_llm_fail = MyAgent()
print(f"\n--- Ejecutando Agente {agent_llm_fail.agent_id} (Caso de Fallo de LLM) ---")
try:
# Simular fallo de LLM
agent_llm_fail._summarize_with_llm("fail_llm_please")
except Exception as e:
print(f"Falló la ejecución del agente como se esperaba: {e}")
Nota cómo `log_agent_step` captura el ID del agente, el nombre del paso, el estado y un diccionario de detalles relevantes. Esto facilita filtrar registros por ID de agente, rastrear una única ejecución o buscar todos los pasos “fallidos”.
Estrategia 2: Observabilidad Centralizada con una Biblioteca/Servicio Dedicado
Para agentes más complejos o entornos de producción, rápidamente superarás la simple grabación en archivos. Aquí es donde los herramientas especializadas brillan. Bibliotecas como `LangSmith` de LangChain (o similares para otros marcos) proporcionan trazado, visualización y depuración integrados para aplicaciones LLM.
Aunque no estés utilizando LangChain, el concepto es transferible. Puedes construir tu propio envoltorio alrededor de la ejecución de tu agente que envíe eventos estructurados a un servicio de registro (Datadog, Splunk, stack ELK, o incluso un simple bucket S3 con procesamiento Lambda). La clave es estandarizar el esquema de eventos.
Mi Proyecto Chronos mejorado ahora utiliza una clase `TraceManager` personalizada que envuelve operaciones críticas. Este administrador envía eventos estructurados a una base de datos local para desarrollo, y a un servicio de registro en la nube en producción. Esto me permite ver un “trazo” completo de cada ejecución del agente, con pasos anidados y todos los datos asociados (prompts, respuestas, entradas/salidas de herramientas, errores).
Estrategia 3: Interceptando Llamadas a LLM y Herramientas
Muchos SDKs de LLM te permiten configurar callbacks o interceptores para llamadas a APIs. ¡Úsalos! En lugar de registrar manualmente antes y después de cada prompt de LLM, puedes tener un único interceptor que registre automáticamente:
- El exacto endpoint de API utilizado.
- Cabeceras y cuerpo de la petición (especialmente el prompt).
- Cabeceras y cuerpo de la respuesta (la finalización).
- Latencia.
- Cualquier excepción.
De manera similar, envuelve tus llamadas a herramientas. Si tienes una herramienta `search_web`, el envoltorio debería registrar la consulta de búsqueda, el motor de búsqueda utilizado, y los primeros N resultados devueltos, junto con cualquier error.
Consejos Accionables para tu Próximo Proyecto de Agente
- Diseña para Observabilidad Primero: No lo trates como un pensamiento posterior. Piensa en lo que necesitarías para depurar incluso antes de escribir tu primer paso de agente.
- Adopta el Registro Estructurado: Deja de lado `print()` y `console.log()` para el código de producción. Utiliza una biblioteca de registro adecuada y emite datos estructurados (JSON) para cada evento significativo.
- Traza Todo lo Importante: Registra el inicio y el fin de cada paso importante, todos los prompts y respuestas de LLM (incluyendo parámetros y conteos de tokens), y cada llamada a herramienta con sus entradas y salidas.
- Captura el Estado en Caso de Fallo: Cuando un agente falla, registra su estado interno o memoria en ese momento. Esto proporciona contexto crucial para entender por qué falló.
- Usa IDs Específicos de Agente: Asigna un ID único a cada ejecución del agente (por ejemplo, un UUID). Esto te permite filtrar y rastrear fácilmente un único camino de ejecución a través de tus registros.
- Visualiza Tus Trazos: Si es posible, utiliza o construye una herramienta que pueda visualizar estos registros estructurados como una secuencia de eventos. Ver el flujo facilita infinitamente la depuración en comparación con hurgar en texto sin procesar. LangSmith lo hace de manera hermosa, pero incluso un script personalizado puede rendir una línea de tiempo HTML simple.
- Monitorea Costos: El uso de tokens LLM es un costo directo. Regístralo. Esto te ayuda a entender a dónde va tu dinero y optimizar tus prompts.
Construir agentes es emocionante, pero construir agentes fiables es donde reside el verdadero trabajo (y el verdadero valor). Y la fiabilidad comienza con saber lo que está sucediendo bajo el capó. Mi dolorosa experiencia con el Proyecto Chronos me enseñó bien esa lección. No esperes a que tu propio “bug misterioso” te convenza. Comienza a registrar de manera inteligente hoy.
¿Cuáles son tus estrategias de observabilidad favoritas para agentes? Contáctame en los comentarios o en las redes sociales. Siempre estoy interesado en escuchar cómo otros enfrentan estos desafíos.
🕒 Published: