Checklist de producción para agentes de IA: logs, monitoreo, alertas, rollback y canary release
"OpenAI Agents SDK tracing registra LLM generations, tool calls, handoffs, guardrails y custom events, y puede usarse para debugging, visualización y monitoreo en desarrollo y producción."
Es viernes por la tarde y estás por abrir tu agente de soporte al 5 % de los usuarios. Los parámetros del canary ya están listos: porcentaje de tráfico, ventana de observación y umbrales de alerta. En la última revisión aparecen tres problemas:
- No hay feature flag; para apagarlo habría que volver a desplegar.
- Nadie sabe cómo mover las tareas de la cola de aprobación humana de vuelta a la versión anterior.
- No está claro si los correos ya enviados cuentan como efectos secundarios de herramientas, ni si el rollback debería revertirlos.
Ninguno de esos problemas aparece como HTTP 500 ni como latencia alta. Lanzar un agente exige ocho dimensiones adicionales frente a un servicio web: trace, tool calls, guardrails, HITL, eval, cost, secrets y checkpoint. Esta checklist las organiza en cuatro grupos: gates antes del release, observación del canary, monitoreo posterior al release y rollback de incidentes.
1. Gates antes del release: diez checks que deben pasar
1.1 Revisión de completitud de Trace
Antes del release, confirma que el trace pueda reconstruir un Agent run completo; si no, el incidente será difícil de reproducir. OpenAI Agents SDK incluye tracing y registra LLM generations, tool calls, handoffs, guardrails y custom events, pero hay que revisar si esa información se conserva completa en producción.
Checklist:
- run ID, trace ID y span ID están correctamente vinculados, y un log de error permite llegar a la solicitud concreta.
- model call, tool call y guardrail result se registran completos, sin campos faltantes.
- los campos de duración, uso de token y código de error están disponibles, para calcular baselines de costo y rendimiento.
- la política de retención de traces y las reglas de redacción son claras, sin eliminar datos útiles por costo de almacenamiento o riesgo de cumplimiento.
- el comportamiento de exportación de traces es consistente entre desarrollo y producción.
Si el trace solo registra el LLM call, sin tool call ni guardrail result, el canary puede verse sano con HTTP 200 aunque los argumentos de herramienta estén mal o se estén cruzando límites de permisos.
1.2 Política de redacción de datos sensibles
Los traces de producción pueden contener PII, secrets y datos de clientes. Antes del lanzamiento hay que decidir qué se captura y cómo se redacta. OpenAI Agents SDK ofrece la configuración trace_include_sensitive_data, que controla si se registran entradas y salidas completas de LLM y tool calls.
Checklist:
- la ubicación y el valor por defecto de
trace_include_sensitive_dataestán claros. - la detección y redacción de PII cubren campos comunes como nombres, correos y teléfonos.
- la separación de secrets está implementada, de modo que API key y contraseñas de bases de datos no aparezcan en traces ni logs.
- los datos de clientes están clasificados como públicos, internos o confidenciales, con reglas de redacción distintas por nivel.
- los traces redactados siguen sirviendo para depurar.
En producción conviene usar detección automática de PII más redacción por niveles. Así cumples requisitos de cumplimiento sin perder capacidad de debugging.
1.3 Gate de monitoreo de Guardrails
Los guardrails validan entradas de usuarios y salidas del agent, y pueden usar un modelo más rápido o barato para bloquear solicitudes no conformes. El tool input guardrail de OpenAI Agents SDK se ejecuta antes de invocar una herramienta de función. Pero los guardrails no son una defensa absoluta. Antes del release hay que confirmar que sean observables, alertables y compatibles con rollback.
Checklist:
- la baseline de tasa de bloqueo del input guardrail ya fue medida.
- se conocen las tasas de falsos positivos y falsos negativos del output guardrail.
- el tool input guardrail se ejecuta antes de llamar a la herramienta.
- los umbrales de alerta de guardrail trip están configurados.
- existe una ruta rápida de feedback para falsos positivos.
El gate de guardrails es simple: tasa de bloqueo con baseline, falsos positivos con feedback y alertas con umbrales.
1.4 Observabilidad de Tool Calls
Los fallos de llamadas a herramientas son uno de los modos de fallo más comunes en agentes. La API HTTP puede devolver 200 aunque los argumentos estén mal, se excedan permisos o un servicio externo haga timeout. Esos fallos no aparecen en el monitoreo normal del servicio; aparecen en el trace.
Checklist:
- la baseline de éxito y fallo de cada herramienta ya fue medida.
- se conoce la distribución de latencia de tool calls (P50/P95/P99).
- los límites de permisos son explícitos, con allowlist o denylist de qué herramientas pueden acceder a qué recursos.
- los modos de fallo están clasificados: timeout, permiso, error de argumentos, fallo de servicio externo, con estrategias diferentes.
- la política de retry y los umbrales de circuit breaker están configurados.
La observabilidad de herramientas exige baseline de éxito por herramienta, fallos clasificados y circuit breaker para timeouts.
1.5 Preparación del monitoreo de cola HITL
La acumulación en colas Human-in-the-Loop (HITL) es un riesgo fácil de pasar por alto durante un canary. Los checkpointers de LangGraph guardan el graph state en cada super-step y soportan HITL, time travel y fault tolerance, pero la longitud de cola y los timeouts de aprobación necesitan monitoreo separado.
Checklist:
- los umbrales de alerta para longitud de cola HITL están configurados.
- la estrategia automática ante timeout de aprobación es clara, con reglas explícitas para rechazar, pasar a humanos o degradar.
- la ruta de resume después de una interrupción fue verificada.
- está definido cómo tratar las tareas en cola durante un cambio de versión.
La cola HITL debe tener umbral, estrategia de timeout y ruta de reanudación comprobada.
1.6 Eval Regression Suite
Antes del release hay que ejecutar una regression suite propia para evitar pérdida de capacidades. La suite debe incluir tareas reales, no solo synthetic examples. Si la tasa de aprobación cae por debajo de la baseline, la nueva versión puede tener problemas y no debería salir.
Checklist:
- la regression suite contiene suficientes tareas reales.
- la baseline de tasa de aprobación es explícita (recomendado: ≥95 %).
- los casos fallidos están claramente clasificados.
- el tiempo de ejecución de la suite está controlado (recomendado: ≤15 minutos).
- el mecanismo para devolver muestras fallidas del canary a la suite está preparado.
La regression suite es el último gate. Si la tasa de aprobación está por debajo de 95 %, conviene corregir antes de lanzar.
1.7 Cost Budget y Rate Limit
Los límites de costo y tasa a nivel de plataforma son la última barrera. OpenAI recomienda usage tracking, billing limits, notification threshold y límites de spend/rate por proyecto. No conviene depender solo de verificaciones de presupuesto dentro del código de negocio.
Checklist:
- los spend limits a nivel de proyecto están configurados.
- los usage notification thresholds están definidos (recomendado: 70 %/90 %).
- los rate limits están segmentados por usuario o tenant.
- las alertas de salto de costo están configuradas, por ejemplo con comparación hora contra hora.
- la estrategia de degradación está clara: apagar herramientas costosas, cambiar de modelo o limitar usuarios al superar el presupuesto.
Cost Budget exige límite superior, alertas con umbrales y una ruta de degradación ante exceso.
1.8 Aislamiento de Secrets y auditoría
La fuga de secrets es uno de los incidentes más graves en agentes. Un agente puede acceder a bases de datos, API de terceros y servicios internos mediante herramientas. Cada llamada necesita auditoría, y los campos actor/subject/tool/resource deben registrarse completos.
Checklist:
- actor/subject/tool/resource se registran completos.
- el almacenamiento de secrets está aislado; API key y contraseñas de base de datos no aparecen en variables de entorno ni archivos de configuración.
- la validación de secrets se ejecuta antes de la llamada a la herramienta.
- el período de retención de audit logs está claro (recomendado: 1 año).
- existe un plan de rotación de claves.
Los audit logs son una base importante para revisar incidentes.
1.9 Validación de recuperación por Checkpoint
Un agente de larga duración debe poder recuperar el estado correcto después de fallar. Los checkpointers de LangGraph guardan el graph state en cada super-step y soportan time travel debugging y fault-tolerant execution, pero la ruta de recuperación debe probarse por separado.
Checklist:
- la frecuencia de guardado de checkpoints está clara, en cada super-step o nodo importante.
- se probó la recuperación después de fallo.
- se verificó la corrección del estado después de recuperar.
- la estrategia de limpieza de tareas a medio terminar está clara.
La recuperación por checkpoint es una capacidad básica para agentes de larga duración.
1.10 Feature Flag y Kill Switch
Debes poder apagar el agente sin volver a desplegar. OpenFeature ofrece un modelo estándar de feature flags, con targeting por tenant, usuario o tipo de tarea, además de rollout porcentual.
Checklist:
- los feature flags están segmentados por tenant, usuario o tipo de tarea.
- el kill switch surte efecto en menos de 1 minuto.
- el rollout porcentual está soportado y puede usarse para canary release.
- el monitoreo y la auditoría del estado de flags están configurados.
Feature Flag exige control segmentado, efecto rápido y auditoría de estado.
2. Observación del canary: qué mirar en los primeros 10-30 minutos
Que los gates previos pasen no significa que el canary no vaya a fallar. Un canary de agentes necesita dos capas de métricas: métricas de servicio (tasa de error HTTP, tiempo de respuesta) y métricas de agente (tool failure rate, guardrail trip rate, cost per run, HITL queue).
2.1 Porcentaje de tráfico y ventana de observación
Un canary no se ejecuta a ojo. Kubernetes y AWS recomiendan empezar con poco tráfico, definir un período de evaluación suficiente, monitorear métricas y luego ampliar gradualmente. Los parámetros de tráfico y tiempo deben estar definidos.
Checklist:
- el porcentaje inicial de tráfico está claro (recomendado: 5-10 %).
- la ventana mínima de observación está definida (recomendado: 10-30 minutos).
- el mínimo de solicitudes dentro de la ventana está configurado.
- las condiciones para ampliar tráfico gradualmente están definidas.
El porcentaje de tráfico y la ventana de observación son parámetros base del canary. Si el 5 % de tráfico dispara alertas en 10 minutos, la nueva versión tiene un problema serio y debe volver atrás de inmediato.
2.2 Monitoreo de métricas de servicio
La tasa de error HTTP, el tiempo de respuesta y el throughput son la primera capa de métricas del canary, igual que en servicios normales. Pero si solo miras esa capa, puedes perder modos de fallo propios de agentes.
Checklist:
- el umbral de tasa de errores HTTP 5xx está configurado (recomendado: ≤1 %).
- el umbral de tiempo de respuesta P95 está claro.
- se monitorea el cambio de throughput frente a la baseline.
- se monitorea uso de CPU y memoria.
- se monitorea la tasa de errores de red.
Las métricas de servicio son la primera defensa, pero no todo el panorama. Un agente puede devolver HTTP 200 mientras fallan tool calls, se saltan guardrails o sube el costo.
2.3 Monitoreo de métricas Agent
Las métricas propias de agentes son la segunda capa del canary. El monitoreo clásico de servicios normalmente no las cubre. Esas señales están en traces, no en HTTP log.
Checklist:
- tool failure rate se monitorea por herramienta.
- guardrail trip rate se monitorea por tipo.
- cost per run se monitorea contra la baseline anterior.
- la longitud de cola HITL se monitorea en tiempo real.
- eval drift se monitorea cuando está disponible.
Las métricas de agente deben agruparse por herramienta y tipo, no promediarse en un único número.
2.4 Condiciones de alerta y rollback automático
Un canary debe poder hacer rollback automático. No puede depender solo de alguien mirando un panel. La documentación de AWS recomienda usar CloudWatch alarms para activar rollback automático, con condiciones y rutas claras.
Checklist:
- las condiciones que disparan rollback automático están definidas.
- la ruta de cambio de tráfico después del rollback está clara.
- la ventana de observación posterior al rollback está definida.
- el flujo de confirmación humana y escalamiento está definido.
El rollback automático exige disparadores claros, ruta de rollback clara y confirmación humana cuando haga falta.
3. Monitoreo posterior al release: producción no termina al lanzar
Un canary aprobado no equivale a production readiness. Después del release hay que seguir monitoreando calidad de traces, uso de costos, efecto de guardrails y eval regression para evitar deriva de capacidades o saltos de costo.
3.1 Monitoreo de calidad de Trace
Después del release, los traces pueden perderse, retrasarse o quedar con campos faltantes, lo que complica la revisión de incidentes y el debugging. El monitoreo de calidad de traces debe estar separado del monitoreo de métricas del servicio.
Checklist:
- se monitorea la completitud de traces, y una correlación de run ID por debajo de baseline dispara alerta.
- se monitorea la latencia de traces, y si tardan más que el umbral en ser consultables se alerta.
- el sampling rate de traces está configurado, con downsampling en alto tráfico para reducir costo de almacenamiento.
- se monitorea el costo de almacenamiento de traces.
La calidad de trace exige baseline de completitud, umbral de latencia y presupuesto de costo.
3.2 Monitoreo continuo de Cost y Usage
Los saltos de costo son uno de los incidentes de producción más comunes en agentes. Uso anómalo de tokens, abuso de modelos o aumento repentino de frecuencia de tool calls pueden disparar el costo. OpenAI recomienda usage tracking y notification threshold.
Checklist:
- se monitorean tendencias diarias de cost, con comparación día contra día y semana contra semana.
- el uso de tokens se monitorea por modelo y por usuario.
- las herramientas de alto costo están identificadas.
- se monitorea la velocidad de consumo del presupuesto.
- el circuit breaker automático ante exceso de presupuesto está configurado.
Monitorear costos significa tener comparaciones de tendencia, clasificación por modelo y circuit breaker de presupuesto.
3.3 Monitoreo continuo de Guardrails
Los cambios en la tasa de bloqueo de guardrails pueden indicar ataques o falsos positivos. Un aumento en input guardrail puede ser más prompts maliciosos; un aumento en falsos positivos de output guardrail puede significar que las reglas están demasiado estrictas.
Checklist:
- se monitorea la tendencia de tasa de bloqueo del input guardrail.
- se monitorea el false positive rate del output guardrail.
- la recolección de feedback de guardrail false positive/negative está completa.
- las reglas de guardrails se evalúan regularmente.
Monitorear guardrails exige tendencia de bloqueo, feedback para falsos positivos y reglas actualizadas.
3.4 Eval regression continua
Después del release, sigue verificando que la capacidad no se degrade. Ejecuta la regression suite diaria o semanalmente, alerta sobre casos fallidos y agrega nuevos fallos a la suite.
Checklist:
- las ejecuciones diarias o semanales de regression suite están automatizadas.
- los casos fallidos disparan alertas automáticamente.
- los nuevos casos fallidos se agregan a la suite.
- la gestión de versiones de la regression suite está en orden.
Eval regression significa ejecuciones periódicas, alertas ante fallos y retroalimentación de casos.
4. Rollback de incidentes: lo difícil son los efectos secundarios de herramientas
El rollback de un agente es más complejo que el de un servicio normal. En un servicio normal suele bastar con volver a una versión de código. En un agente también hay que tratar efectos secundarios de herramientas ya ejecutadas, workflows a medio terminar y tareas en colas de aprobación humana.
4.1 Rollback de código
El rollback de código es el camino más simple. Kubernetes Deployment soporta rolling update y rollback, pero la ventana de rollback debe mantenerse dentro de 5 minutos.
Checklist:
- la ruta de rollback de versión de código está clara.
- el cambio de tráfico después del rollback fue verificado.
- se ejecuta validación posterior al rollback, como smoke test.
- la ventana de rollback está definida (recomendado: ≤5 minutos).
Rollback de código exige ruta clara, cambio verificado y ventana limitada.
4.2 Rollback de efectos secundarios de herramientas
Lo más difícil al rollbackear un agente son los efectos secundarios de herramientas que ya se ejecutaron. Enviar correos, crear pedidos o llamar API externas no se deshace porque el código vuelva atrás. Hay que separar operaciones idempotentes y no idempotentes, y diseñar acciones de compensación.
Checklist:
- las operaciones de herramienta ya ejecutadas están identificadas, y cada tool call ejecutado puede encontrarse en traces.
- las operaciones idempotentes pueden repetirse de forma segura.
- las operaciones no idempotentes tienen acciones de compensación: enviar un correo correctivo, cancelar un pedido o llamar una API de reversa.
- la estrategia de limpieza de tareas a medio terminar está clara.
- el proceso de respaldo humano está definido.
El rollback de efectos secundarios exige identificar operaciones ejecutadas, evaluar idempotencia y diseñar compensaciones.
4.3 Limpieza de cola HITL
Durante un rollback, la cola de aprobación humana puede quedar con tareas a medio terminar. La nueva versión del agente puede haber escalado tareas a HITL, mientras que la versión anterior no requería aprobación humana. Las tareas en cola deben reasignarse o volver atrás.
Checklist:
- las tareas de la cola se identifican por etiqueta de versión.
- la estrategia de reasignación de tareas está clara.
- el manejo de timeout de aprobación está definido.
- el flujo de confirmación humana está completo.
La limpieza de cola HITL exige identificación por versión, estrategia de reasignación y manejo de timeout.
4.4 Retención de Trace y Audit logs
La revisión posterior a incidentes necesita traces y audit logs completos. OpenTelemetry trata logs como uno de los telemetry signals y puede integrarlos con logging frameworks existentes.
Checklist:
- el período de retención de traces está claro (recomendado: 30-90 días).
- el período de retención de audit logs está claro (recomendado: 1 año).
- las reglas de redacción de datos sensibles están completas.
- se cumplen los requisitos de cumplimiento del sector.
La retención de Trace y Audit exige períodos adecuados, reglas de redacción completas y cobertura de cumplimiento.
4.5 Devolver muestras fallidas a la Eval Suite
Después de un incidente, las muestras fallidas deben agregarse a la regression suite para evitar que se repita el mismo tipo de incidente. La extracción debe encontrar failed cases en traces, y una persona debe etiquetar causa de fallo y comportamiento esperado.
Checklist:
- existe una herramienta o script para extraer muestras fallidas.
- el etiquetado de muestras tiene confirmación humana.
- existe un proceso para agregar muestras a la regression suite.
- existe un mecanismo para evitar que el mismo incidente se repita.
La retroalimentación de fallos exige extracción, etiquetado humano, proceso de actualización de suite y fixes verificados.
Conclusión
Lanzar un agente exige ocho dimensiones adicionales frente a un servicio web normal: trace, tool calls, guardrails, HITL, eval, cost, secrets y checkpoint. Esas dimensiones se agrupan en cuatro checklists:
Gates antes del release (10 checks): completitud de Trace, redacción de datos sensibles, monitoreo de Guardrails, observabilidad de Tool Calls, preparación de cola HITL, Eval Regression Suite, Cost Budget y Rate Limit, aislamiento de Secrets y auditoría, validación de recuperación por Checkpoint, Feature Flag y Kill Switch. Revísalos uno por uno antes del release. Lo que no pase debe bloquear el lanzamiento.
Observación del canary (4 checks): porcentaje de tráfico y ventana de observación, monitoreo de métricas de servicio, monitoreo de métricas Agent, condiciones de alerta y rollback automático. Un canary no mira solo tasa de error HTTP; también mira tool failure rate, guardrail trip rate, cost per run y HITL queue length.
Monitoreo posterior al release (4 checks): calidad de Trace, monitoreo continuo de Cost y Usage, monitoreo continuo de Guardrails y Eval regression continua. Un canary limpio no basta; el monitoreo sostenido evita deriva de capacidad y saltos de costo.
Rollback de incidentes (5 checks): rollback de código, rollback de efectos secundarios de herramientas, limpieza de cola HITL, retención de Trace y Audit logs, y devolución de muestras fallidas a la Eval Suite. Rollback no es solo volver a una versión de código. También hay que tratar tool side effects ejecutados, workflows a medio terminar y colas de aprobación humana.
Guarda estas cuatro checklists como plantilla y recórrelas antes de cada release. Si un check falla, corrígelo antes de salir a producción en lugar de llevar un problema conocido al canary.
Ejecutar una revisión de producción antes de lanzar un agente
Antes de mover un agente del demo a usuarios reales, revisa observabilidad, gates de release, control de costos, seguridad y rutas de rollback antes del release, durante el canary, después del release y en incidentes.
- 1
Step 1: Correlacionar identificadores de ejecución
Confirma que runId, traceId, spanId, toolCallId, userId/tenantId y workflowVersion se puedan correlacionar entre logs, traces y alertas. - 2
Step 2: Revisar la política de datos sensibles
Confirma que prompts, argumentos de herramientas, respuestas de herramientas, secrets y PII estén redactados, con períodos de retención y controles de acceso. - 3
Step 3: Ejecutar evaluaciones de regresión
Ejecuta la eval regression suite más reciente, cubriendo respuestas finales, selección de herramientas, argumentos, transiciones de estado, permisos, costo y recuperación ante fallos. - 4
Step 4: Validar rutas de fallo
Valida las rutas de fallo de guardrails, HITL, permisos, secret vault, cost budget, rate limit y retry budget. - 5
Step 5: Preparar interruptores de rollout
Prepara feature flag, kill switch, per-tenant enablement, canary percentage, observation window y rollback conditions. - 6
Step 6: Monitorear métricas del canary
Durante el canary, monitorea juntas las métricas normales del servicio y las métricas del agente: tool failure, guardrail trip, cost per run, approval queue y checkpoint resume. - 7
Step 7: Confirmar la operación posterior al release
Después del release, confirma alertas, on-call, runbooks, plantillas de postmortem y el proceso para devolver traces fallidos a las evaluaciones. - 8
Step 8: Contener primero el incidente
Durante un incidente, primero apaga el flag o vuelve a la versión anterior; después trata tareas a medio terminar, efectos secundarios externos y regression cases.
FAQ
¿Qué debo revisar antes de lanzar un agente si el demo ya funciona?
¿En qué se diferencia lanzar un agente de lanzar un servicio web normal?
¿Qué métricas debo mirar durante un canary release de un agente?
¿Puedo guardar prompts completos y argumentos de herramientas en los traces?
¿Hacer rollback de un agente es solo volver a una versión anterior del código?
¿Los guardrails pueden reemplazar la aprobación humana o el modelo de permisos?
17 min de lectura · Publicado el: 21 oct 2026
Guía de ingeniería de AI Agents
Si llegaste desde búsqueda, lo más rápido es ir al artículo anterior o siguiente de esta misma serie.
Anterior
Cómo crear un dataset de evaluación de agentes: tareas reales, trayectorias y pruebas de regresión
No te quedes solo con benchmarks públicos. Esta guía muestra cómo convertir tareas reales de agentes, traces, tool calls, eventos de estado, feedback humano y casos de fallo en un eval dataset para pruebas de regresión y release gates.
Parte 23 de 24
Siguiente
Este es el artículo más reciente de la serie por ahora.
Comentarios
Inicia sesión con GitHub para dejar un comentario