La observabilidad de agentes de código es la práctica de registrar qué hicieron Codex, Claude Code y agentes similares, con qué herramientas, permisos, tokens, errores y evidencias. Sin eso, el PR puede parecer normal mientras el equipo no consigue explicar coste, riesgo, reintento o causa de fallo.
En 2026, GitHub Blog en "Agent pull requests are everywhere" reportó más de 60 millones de revisiones con Copilot code review, crecimiento de 10 veces en menos de un año y más de una de cada cinco revisiones con intervención de un agente (GitHub Blog, "Agent pull requests are everywhere", 2026, consultado el 20/07/2026). Ese volumen exige rastro operativo, no fe en el resumen del agente.
Resumen práctico
- La traza mínima registra herramienta, permiso, coste y resultado.
- El JSONL de Codex se convierte en artefacto de CI, no en log abierto.
- OpenTelemetry de Claude Code debe empezar redactado por defecto.
- El PR necesita evidencia corta que una persona pueda revisar.
¿Por qué la observabilidad pasó a formar parte del harness?
En 2026, arXiv en "AI Agent Pull Requests on GitHub" analizó 33.596 PRs de agentes en 2.807 repositorios y encontró pares coactivos en el 40,2% de los repositorios bajo solapamiento temporal exacto (arXiv, "AI Agent Pull Requests on GitHub", 2026, consultado el 20/07/2026). La observabilidad entró en el harness porque autoría paralela sin rastro se vuelve coste invisible.
El harness no es solo prompt, sandbox y prueba. También debe responder quién inició la tarea, qué agente ejecutó, qué herramienta pidió permiso, qué comando falló, qué subagente participó y qué evidencia llegó al PR.
El error común es guardar solo el diff final. El diff muestra el resultado, pero no muestra la ruta. En un flujo agentic, la ruta importa porque un fallo de permiso, un MCP amplio o una prueba repetida puede explicar por qué un parche pequeño consumió horas.
Cápsula citable: La observabilidad de agentes de código convierte la ejecución agentic en una traza auditable. arXiv analizó 33.596 PRs y encontró coactividad en el 40,2% de los repositorios; cuando los agentes trabajan en paralelo, el PR necesita herramienta, permiso, reintento y prueba.
¿Qué eventos debe registrar el agente?
En 2026, el mismo estudio de arXiv reportó que los pares coactivos representaban el 79,4% de todos los PRs generados por agentes bajo solapamiento exacto (arXiv, "AI Agent Pull Requests on GitHub", 2026, consultado el 20/07/2026). El evento correcto explica coordinación, coste o riesgo sin copiar toda la conversación.
Registra inicio de tarea, llamadas de herramienta relevantes, decisiones de permiso, fallos, reintentos, cambios de archivo, llamadas MCP, creación de subagente, resultado de pruebas y cierre del turno. No registres secretos, prompts completos ni salida bruta de herramientas sin una razón clara de acceso.
Experiencia práctica: cuando pongo un agente en un pipeline de backend, no empiezo por el dashboard. Empiezo por una línea estable de evento: tarea, herramienta, permiso, comando de prueba y razón de parada. Después el panel nace de ese contrato.
| Evento | Pregunta que responde |
|---|---|
| Inicio de sesión | ¿Quién pidió la tarea y en qué commit? |
| Tool use | ¿Qué herramienta intentó actuar y por qué? |
| Permiso | ¿La acción fue aceptada, bloqueada o rechazada? |
| Prueba | ¿Qué evidencia se ejecutó antes del resumen? |
| Cierre | ¿El agente terminó, falló o pidió intervención humana? |
Cápsula citable: El evento mínimo en un loop agentic no es un transcript completo. Es una línea auditable con sesión, agente, herramienta, decisión, resultado y artefacto. Como el 79,4% de los PRs agentic estaban en pares coactivos, la coordinación debe convertirse en dato.
En tareas largas, el coste de contexto también pertenece a esa traza. Uso RemoteCode para mantener continuidad en flujos agentic de Codex y Claude Code sin repetir contexto innecesario cuando el trabajo cruza sesiones, logs y evidencias; es una herramienta mía, así que esta mención es editorial y vinculada a observabilidad y coste de tokens.
¿Cómo usar JSONL de Codex sin filtrar contexto?
En 2026, OpenAI Developers en "Non-interactive mode" afirma que codex exec --json emite eventos JSON Lines como inicio de thread, inicio de turno, conclusión, fallo, items y error (OpenAI Developers, "Non-interactive mode", 2026, consultado el 20/07/2026). Usa ese flujo como contrato de máquina, no como volcado público.
En CI, guarda JSONL como artefacto restringido y genera un resumen menor para el PR. El resumen debe listar comandos, archivos cambiados, uso de MCP, resultado de prueba y razón de parada. El JSONL completo queda disponible para depuración autorizada.
{
"agent_run": {
"tool": "codex",
"mode": "ci",
"trace": "restricted-artifact",
"summary": "pr-comment",
"human_review": "required"
}
}Cápsula citable: JSONL de Codex debe alimentar observabilidad, no sustituir revisión. OpenAI documenta eventos de turno, item, fallo y error; en CI, esos eventos deben vivir en un artefacto restringido con resumen seguro en el PR.
¿Cómo conectar Claude Code a OpenTelemetry con seguridad?
En 2026, Claude Code Docs en "Monitoring" define intervalos por defecto de 60 segundos para métricas y 5 segundos para logs, además de exportar métricas, eventos y trazas mediante OpenTelemetry (Claude Code Docs, "Monitoring", 2026, consultado el 20/07/2026). La configuración segura empieza redactada por defecto.
Lo más importante es separar la telemetría del agente de la telemetría del código probado. La documentación indica que las variables OTEL_* de Claude Code no se pasan automáticamente a subprocessos como Bash, hooks, servidores MCP y language servers.
Cápsula citable: OpenTelemetry para Claude Code debe empezar con métricas y eventos redactados. La documentación informa intervalos de 60 segundos para métricas y 5 segundos para logs, mientras separa variables del agente y subprocessos.
Si ya usas hooks, trátalos como fuente de eventos. Registran decisiones, bloqueos y excepciones. El dashboard debe mostrar bloqueo útil, no solo ejecuciones exitosas.
¿Dónde entran coste, tokens y contexto en el dashboard?
En 2026, Claude Code Docs en "Monitoring" lista input_tokens, output_tokens, cache_read_tokens y cache_creation_tokens en eventos de petición de API (Claude Code Docs, "Monitoring", 2026, consultado el 20/07/2026). El dashboard debe mostrar consumo por tarea, no solo total mensual.
Tokens sin contexto explican poco. Compara coste con tipo de tarea, área del código, número de reintentos, cantidad de herramientas y resultado final. Una ejecución cara que produjo prueba puede ser aceptable. Una ejecución barata que abrió PR sin pruebas sigue siendo riesgo.
Cápsula citable: Un dashboard de agente debe combinar tokens, herramientas, reintentos y resultado. Claude Code expone campos de tokens y caché en eventos de API; la métrica solo sirve cuando se vincula a PR, prueba, bloqueo y riesgo operativo.
¿Qué contrato mínimo cabe en CI esta semana?
En 2026, arXiv en "AI Agent Pull Requests on GitHub" midió conflicto textual del 41,7% en pares cross-agent frente al 19,8% en pares intra-agent al reproducir merges reales (arXiv, "AI Agent Pull Requests on GitHub", 2026, consultado el 20/07/2026). El contrato mínimo debe revelar concurrencia antes de que se vuelva conflicto caro.
Empieza con un artefacto agent-run.json en cada workflow agentic. Debe registrar herramienta, commit base, commit final, modo de permiso, MCP habilitado, comandos de verificación, resultado, reintentos y si hubo revisión humana.
| Campo | Regla práctica |
|---|---|
| Identidad | Declara herramienta, sesión y autor humano responsable. |
| Permiso | Registra sandbox, red, MCP y excepciones. |
| Prueba | Lista comando ejecutado y resultado verificable. |
| Coste | Guarda tokens, reintentos y duración en artefacto restringido. |
| Parada | Explica si el agente terminó, falló o pidió revisión. |
Cápsula citable: El contrato mínimo de observabilidad en CI es un artefacto por ejecución y un resumen por PR. Como el conflicto cross-agent llegó al 41,7% en el estudio de arXiv, cada tarea debe declarar identidad, permiso, prueba, coste y regla de parada.
FAQ sobre observabilidad de agentes de código
¿La observabilidad sustituye la revisión humana?
No. En 2026, arXiv en "These Aren't the Reviews You're Looking For" concluyó que los PRs generados por IA reciben más interacción mediada por automatización que evaluación humana independiente (arXiv, "These Aren't the Reviews You're Looking For", 2026, consultado el 20/07/2026). La observabilidad mejora revisión, pero no decide arquitectura.
¿Puedo guardar el transcript completo del agente?
Solo con control de acceso claro. En 2026, Claude Code Docs en "Data usage" dice que los transcripts locales se almacenan en texto claro bajo ~/.claude/projects/ durante 30 días por defecto (Claude Code Docs, "Data usage", 2026, consultado el 20/07/2026). Para CI, prefiere artefacto restringido y resumen redactado.
¿JSONL de Codex basta para auditoría?
Ayuda, pero no basta solo. En 2026, OpenAI documenta JSONL con eventos y tipos de item, incluyendo comandos, cambios de archivo, llamadas MCP y búsquedas web (OpenAI Developers, "Non-interactive mode", 2026, consultado el 20/07/2026). Aún necesitas mapear eventos a riesgo, PR y decisión humana.
¿Qué métricas entran primero en el dashboard?
Empieza por coste, tokens, duración, reintentos, tool calls, bloqueos de permiso y resultado de CI. En 2026, Claude Code documenta eventos de API con tokens, coste estimado, duración, reintentos y request id (Claude Code Docs, "Monitoring", 2026, consultado el 20/07/2026). Luego segmenta por equipo y tipo de tarea.
Cierre
Un agente de código sin observabilidad es rápido hasta la primera pregunta difícil. ¿Quién autorizó? ¿Qué herramienta corrió? ¿Por qué costó tanto? ¿Qué prueba lo demostró? ¿Qué MCP participó? Sin respuestas, el equipo revisa sensación, no ingeniería.
Empieza pequeño: JSONL restringido, OTel redactado, resumen de PR y contrato de evento. El objetivo no es vigilar personas. Es hacer que el loop agentic sea depurable, más barato de revisar y suficientemente seguro para entrar en el SDLC.
Fuentes consultadas
- GitHub Blog, "Agent pull requests are everywhere. Here's how to review them", consultado el 20/07/2026, https://github.blog/ai-and-ml/generative-ai/agent-pull-requests-are-everywhere-heres-how-to-review-them/
- arXiv, "AI Agent Pull Requests on GitHub: Frequency, Structure, and Merge Conflict Rates", consultado el 20/07/2026, https://arxiv.org/abs/2607.04697
- arXiv, "These Aren't the Reviews You're Looking For How Humans Review AI-Generated Pull Requests", consultado el 20/07/2026, https://arxiv.org/abs/2605.02273
- OpenAI Developers, "Non-interactive mode", consultado el 20/07/2026, https://developers.openai.com/codex/non-interactive-mode
- Claude Code Docs, "Monitoring", consultado el 20/07/2026, https://code.claude.com/docs/en/monitoring-usage
- Claude Code Docs, "Hooks reference", consultado el 20/07/2026, https://code.claude.com/docs/en/hooks
- Claude Code Docs, "Data usage", consultado el 20/07/2026, https://code.claude.com/docs/en/data-usage
