Idea en 30 segundos
La observabilidad para agentes de IA muestra qué ocurre durante un run.
Un agente puede hacer decenas de pasos: reasoning, tool calls, llamadas repetidas al LLM.
La observabilidad hace visibles esos pasos con tracing, logs y métricas.
Problema principal
En un backend clásico, una solicitud HTTP ejecuta código predecible:
request → handler → database → response
La cantidad de pasos se conoce de antemano, y el comportamiento se sigue fácilmente con logs normales.
En sistemas con agentes de IA funciona distinto: una sola solicitud puede convertirse en un run con varios pasos de reasoning, tool calls e iteraciones repetidas.
Un agente puede hacer 2 pasos o 20. Puede llamar varias herramientas, repetir reasoning varias veces y gastar más tokens de lo esperado.
Sin observabilidad, cuesta responder incluso preguntas básicas:
- ¿Por qué la solicitud va lenta?
- ¿Por qué subieron de golpe los costos de tokens?
- ¿Por qué el agente llama una herramienta decenas de veces?
- ¿En qué paso apareció el error?
Para estos sistemas, los logs comunes no alcanzan. Se necesita observabilidad para ver todo el camino de ejecución y encontrar rápido los pasos problemáticos durante debugging.
Cómo funciona
La observabilidad para agentes de IA se basa en tres tipos de señales: traces, logs y métricas. Juntas permiten ver tanto solicitudes individuales como el estado general del sistema.
Existen herramientas especializadas de observabilidad para agentes (por ejemplo LangSmith, Langfuse, Arize Phoenix), pero los principios base son iguales sin importar la herramienta.
Tracing
El tracing muestra el camino completo de ejecución de un run del agente.
Cada paso se registra como evento: reasoning del modelo, llamada de herramienta o resultado.
Un trace está compuesto por spans (spans).
El trace es el camino completo de ejecución (run), y un span es un paso dentro de él, por ejemplo una llamada de herramienta o reasoning.
run_id: 9fd2
step 1 — search_docs 420ms
step 2 — summarize 110ms
step 3 — generate_answer 890ms
El tracing muestra qué tools llamó el agente y cuántos pasos hizo. También se ve dónde apareció un error o una latencia.
Cómo se ve un trace de agente
La forma más simple de entender tracing es con una solicitud real.
Ejemplo de trace de una solicitud:
run_id: 9fd2
user_query: "Find recent research about battery recycling"
step 1 llm_reasoning 320ms
thought: need to search research papers
step 2 tool_call: search 410ms
query: battery recycling research 2024
step 3 llm_reasoning 180ms
thought: summarize the most relevant papers
step 4 tool_call: fetch 260ms
source: arxiv
step 5 llm_generate 720ms
output: final answer
Este trace permite entender rápido:
- qué pasos ejecutó el agente
- qué herramientas fueron llamadas
- cuánto tardó cada paso
- dónde apareció la latencia o el error
En sistemas de producción, un trace suele incluir información adicional:
- run_id y trace_id para correlacionar eventos
- latency de cada paso
- token usage del LLM
- stop reason (
completed,max_steps,tool_error)
Los traces no solo sirven para debugging. También son necesarios para evaluations. Sin pasos intermedios, es difícil verificar automáticamente si el agente actuó correctamente durante el run, y no solo si dio una respuesta final correcta.
Logging
Los logs registran eventos durante la ejecución del agente:
- inicio y fin del run
- tool calls con parámetros
- errores y excepciones
- motivo de parada del agente (stop reason)
Los logs responden a la pregunta «qué pasó». El tracing responde «cómo exactamente pasó».
Métricas
Las métricas muestran el estado general del sistema, no una solicitud concreta. Métricas típicas de producción para agentes:
| Métrica | Qué muestra |
|---|---|
| run count | cantidad de ejecuciones en el tiempo |
| latency p50/p95 | velocidad de respuesta |
| tool calls per run | carga sobre herramientas |
| token usage | consumo de costo LLM |
| error rate | frecuencia de fallos |
Las métricas son necesarias para monitoreo y alertas en production. Permiten ver anomalías rápido: por ejemplo, crecimiento repentino de token usage, latency o cantidad de tool calls.
La mayoría de los proveedores LLM (OpenAI, Anthropic) devuelven token usage en la respuesta, así que normalmente no hace falta calcularlo a mano: basta con loggear esos campos.
Cuándo usar
La observabilidad no siempre es necesaria.
Para escenarios simples suele alcanzar con logging básico. Por ejemplo, cuando hay una sola llamada LLM sin tools y sin ciclo de ejecución.
Pero en cuanto aparece un run con varios pasos — reasoning, tool calls, iteraciones repetidas — sin observabilidad se vuelve difícil debugear el sistema, controlar costos y explicar su comportamiento.
Ejemplo de implementación
Abajo hay un ejemplo simplificado de instrumentation en un runtime de agente.
En sistemas reales, estos eventos suelen enviarse a un sistema de tracing o a una plataforma de observabilidad.
En la mayoría de runtimes, cada unidad de ejecución se representa como step: puede ser reasoning del modelo o llamada de herramienta.
Este ciclo (agent.iter) se usa en frameworks como LangGraph, CrewAI y en runtimes propios.
import logging
import time
import uuid
logger = logging.getLogger("agent")
def run_agent(agent, task):
run_id = str(uuid.uuid4())
logger.info("agent_run_started", extra={
"run_id": run_id,
"task": task,
})
steps = []
for step in agent.iter(task): # step: reasoning o tool execution
step_start = time.time()
result = step.execute()
latency = time.time() - step_start
step_event = {
"run_id": run_id,
"step_type": step.type, # reasoning | tool_call | llm_generate
"tool": getattr(step, "tool_name", None),
"latency": latency,
}
logger.info("agent_step", extra=step_event)
steps.append(step_event)
if result.is_final:
break
logger.info("agent_run_finished", extra={
"run_id": run_id,
"steps": len(steps),
})
Las herramientas se pueden envolver en un wrapper para loggear tanto llamadas exitosas como errores:
def traced_tool(tool_fn):
def wrapper(*args, **kwargs):
start = time.time()
try:
result = tool_fn(*args, **kwargs)
logger.info(
"tool_call",
extra={
"tool": tool_fn.__name__,
"latency": time.time() - start,
"status": "ok",
},
)
return result
except Exception as error:
logger.error(
"tool_call_failed",
extra={
"tool": tool_fn.__name__,
"latency": time.time() - start,
"error": str(error),
},
)
raise
return wrapper
El ejemplo anterior muestra la lógica base de instrumentation. En sistemas de production suele ampliarse con varias prácticas:
- trace_id para cada run
- logs estructurados (JSON)
- métricas de latency y token usage
- integración con sistemas de monitoreo
Por ejemplo, un registro estructurado puede verse así:
{
"timestamp": "2026-03-21T15:17:00Z",
"level": "INFO",
"event": "tool_call",
"run_id": "9fd2...",
"tool": "search_docs",
"latency_ms": 410,
"status": "ok"
}
En sistemas reales, run_id y trace_id deben propagarse por toda la cadena de llamadas.
En Python, para eso suele usarse contextvars, así no hace falta pasar el identificador como argumento a cada función.
Esto ayuda a ver el camino completo de ejecución del agente y encontrar rápido pasos problemáticos.
Errores típicos
Incluso cuando ya hay observabilidad, los sistemas con agentes suelen seguir siendo difíciles de diagnosticar. Muchas veces por errores típicos como estos.
Loggear solo la respuesta final
Si el sistema registra solo el resultado final, es imposible entender cómo llegó el agente a esa respuesta. Por eso es importante loggear pasos de reasoning, tool calls y stop reason. Sin esto, incluso incidentes simples después del release son difíciles de analizar.
No tener traces de llamadas de herramientas
Las herramientas suelen ser la parte más lenta del sistema. Si las llamadas no entran en tracing, cuesta entender:
- qué tool está introduciendo latencia
- dónde exactamente aparece el error
- si el agente está repitiendo la misma herramienta
En production, esto suele ocultar spam de herramientas o una etapa temprana de fallos en cascada.
No tener métricas de costo
Los agentes pueden aumentar costos sin que se note, por ciclos largos de reasoning, llamadas repetidas al LLM o tool calls innecesarias. Sin métricas de costo, esto suele detectarse recién cuando la factura sube claramente. Como resultado, el sistema puede entrar rápido en un modo caro e inestable.
Loggear prompts en crudo
Los prompts pueden incluir datos personales, secretos o información interna. Antes de escribirlos en logs, conviene redactarlos o anonimizarlos. Si no, durante incidentes pueden quedar datos sensibles en los logs.
Autoevaluación
Abajo tienes un checklist corto de observabilidad base para production.
Progreso: 0/9
⚠ Falta observability base
Será difícil depurar el sistema en production. Empieza con run_id, structured logs y tracing de tool calls.
FAQ
Q: ¿Cuál es la diferencia entre tracing, logs y métricas?
A: Tracing muestra el camino de un run paso a paso. Logs registra eventos y errores. Métricas muestra la vista global en un período (latency, error rate, token usage).
Q: ¿Qué implementar primero si todavía no hay observabilidad?
A: Empieza por lo mínimo: run_id, logs estructurados y latency por paso. Luego agrega tracing para tool calls y métricas clave (token usage, tool calls per run, error rate).
Q: ¿Qué campos son más importantes para debugear un run problemático?
A: Mínimo: run_id/trace_id, tipo de paso, herramienta llamada, latency del paso, stop reason, error (si hubo). Eso alcanza para reconstruir la cadena de eventos.
Q: ¿Es obligatorio usar herramientas externas de observabilidad desde el inicio?
A: No. Puedes empezar con instrumentation propia y logs estructurados. Las plataformas especializadas tienen más sentido cuando crecen el volumen de runs, el número de equipos y la necesidad de análisis centralizado.
Páginas relacionadas
Siguiente lectura del tema:
- Tracing del agente — cómo seguir la ejecución de un run.
- Tracing distribuido de agentes — tracing entre varios agentes.
- Métricas de agentes — qué indicadores medir.