Coding agent sin freno: presupuesta intentos, no tokens

TL;DR: Reducir el contexto por sí solo no suele corregir un agente que encadena búsquedas, cambios y pruebas sin una condición de parada. Aprenderás a asignar turnos, tiempo y una validación externa según el riesgo de la tarea, con un contrato copiable y un runner en Python.

El instinto lógico que optimiza la métrica equivocada

Ya tienes el dedo encima de recortar el prompt o cambiar de modelo. Parece lógico: si la sesión consume demasiado, cada llamada debe ser más pequeña o barata. El problema aparece cuando el gasto nace del número de intentos, no del tamaño inicial del contexto.

Un coding agent suele recorrer un bucle: inspecciona, propone, edita, ejecuta una herramienta, interpreta el resultado y vuelve a intentarlo. En muchos agentes, cada follow-up incorpora parte del historial anterior. Un comando irrelevante no solo consume una llamada: añade resultados que condicionan las siguientes decisiones.

Quitar contexto a ciegas puede empeorar ese bucle. El agente vuelve a buscar lo que ya no recuerda, repite comandos o edita el archivo equivocado. Si tu problema está en la caché, conviene tratarlo como explica esta guía para recortar tokens sin romper el cache hit rate. Aquí la pregunta es distinta: ¿cuánto trabajo puede intentar antes de detenerse?

Un presupuesto de esfuerzo para un coding agent es un contrato que limita turnos y tiempo, define una prueba de aceptación externa y obliga a parar cuando la tarea deja de progresar. No mide cuánto habla el agente, sino cuánto margen recibe para entregar un resultado verificable.

Mide intentos antes de tocar el presupuesto

La unidad útil es la tarea terminada dentro del límite. Los tokens siguen importando para facturación y capacidad, pero no indican por sí solos si el agente avanzó.

A 03/07/2026, las métricas oficiales de GitHub Copilot CLI separan prompt_count, que cuenta entradas humanas, de request_count, que también incluye llamadas agénticas automáticas. También publican tokens de entrada, salida y media por solicitud mediante API. La definición exacta está en la documentación oficial de métricas de Copilot.

Con esos campos puedes calcular este indicador diagnóstico:

follow_up_ratio = (request_count - prompt_count) / max(prompt_count, 1)

Un valor alto no demuestra desperdicio. Una migración transversal suele necesitar más comprobaciones que un cambio de texto localizado. Sirve para localizar clases de tareas donde crecen los intentos sin mejorar el resultado.

• Éxito dentro del presupuesto: tareas cuyo gate pasa antes del límite dividido entre tareas iniciadas.
• Agotamiento: tareas que llegan al límite sin pasar el gate.
• Tiempo hasta verificación: desde el prompt hasta la ejecución externa satisfactoria.
• Motivo de parada: éxito, timeout, límite de turnos, permiso o bloqueo técnico.

Separa estas métricas de la elección comercial del modelo. Para esa decisión ya tienes un marco centrado en coste real y evaluaciones propias.

La regla: autonomía solo con salida verificable

Si existe un gate determinista y el alcance está localizado, asigna un límite y deja ejecutar al agente. Si la aceptación depende de criterio humano o el cambio amplía su radio de acción, pide primero un plan.

La política concreta es esta:

• Si el agente puede demostrar el resultado con tests, lint, compilación o una consulta de solo lectura, autoriza ejecución acotada.
• Si toca autenticación, permisos, datos, migraciones o contratos públicos, exige plan y aprobación antes de editar.
• Si agota el presupuesto, no dupliques el límite automáticamente. Conserva diff, salida del gate y bloqueo, y decide si debes dividir la tarea o intervenir.

Esta separación entre planificar, modificar y verificar aplica el mismo principio que la separación de responsabilidades en arquitectura: una capa propone el cambio y otra determina si cumple el contrato.

Los números siguientes son umbrales prácticos iniciales, no resultados de un benchmark. Ajústalos con tus propias tareas.

Artefacto: contrato de esfuerzo para cada tarea

Copia esta ficha en tu issue, job de CI o comando interno. Evita que “terminar” signifique lo que el agente decida al final de la sesión.

TASK: [cambio concreto]
SCOPE: [archivos o módulo permitido]
ACCEPTANCE_GATE: [comando determinista]
MAX_TURNS: [límite de iteraciones]
TIMEOUT_SECONDS: [límite de reloj]
STOP_IF: [condiciones que requieren ayuda]
ON_EXHAUSTION: devolver diff + gate output + blocker
FORBIDDEN: [datos, comandos o rutas fuera de alcance]

Ejemplo: corregir la serialización de fechas en src/orders/, ejecutar pnpm test -- orders, parar si exige modificar el esquema de base de datos y devolver evidencias si no pasa tras seis turnos.

Claude Code ofrece --max-turns en modo no interactivo y salida JSON, según su referencia oficial de CLI. El límite de turnos no sustituye al timeout ni comprueba que el resultado sea correcto.

Qué hace: este wrapper limita los turnos y el tiempo, y después ejecuta el gate fuera del agente para no aceptar su propia declaración de éxito.

import os, shlex, subprocess

task = os.environ["AGENT_TASK"]
gate = os.environ["AGENT_GATE"]
turns = os.getenv("AGENT_MAX_TURNS", "6")
timeout = int(os.getenv("AGENT_TIMEOUT_SECONDS", "900"))
prompt = f"{task}\nAcceptance gate: {gate}\nStop and report blockers if it still fails."
agent = subprocess.run(["claude", "-p", "--max-turns", turns, "--output-format", "json", prompt], capture_output=True, text=True, timeout=timeout)
verification = subprocess.run(shlex.split(gate), timeout=timeout)
print(agent.stdout)
raise SystemExit(agent.returncode or verification.returncode)

Ejecútalo con AGENT_TASK='Corrige la serialización de fechas en src/orders' AGENT_GATE='pnpm test -- orders' python run_agent.py. shlex.split ejecuta comandos simples sin operadores de shell; para pipelines, usa un script versionado como gate.

Ajusta el presupuesto con tareas comparables

No uses una media global para todo el repositorio. Agrupa las ejecuciones por clase: documentación, bug localizado, refactor, dependencia o migración.

Como umbral práctico propio, reúne entre 20 y 50 tareas por clase antes de endurecer una política compartida. Registra el presupuesto inicial y no lo cambies durante esa muestra. Después revisa:

• Si el gate pasa pronto de forma consistente, reduce el límite de esa clase.
• Si muchas tareas llegan al límite con el mismo bloqueo, mejora el contexto, los permisos o la reproducibilidad antes de comprar más esfuerzo.
• Si los fallos son heterogéneos, divide la categoría: “bug con test” y “bug sin reproducción” no deberían compartir presupuesto.
• Si subir turnos mejora el éxito pero también amplía diffs y revisiones, introduce hitos más pequeños.

El presupuesto pertenece al flujo, no a la marca de la herramienta. Si aún estás decidiendo qué CLI encaja con tu repositorio, utiliza un mini-eval ejecutado sobre tareas reales del repo y añade el agotamiento del presupuesto como señal.

Fallos típicos al llevarlo a producción

Un límite mal diseñado puede limitarse a convertir un fallo silencioso en uno rápido. Revisa estos puntos antes de automatizarlo en CI:

• Gate débil: “el diff parece correcto” no es verificable. Usa un comando con código de salida y conserva su salida.
• Timeout ausente: un único test bloqueado puede consumir el job aunque el agente no complete otro turno.
• Reintento ciego: relanzar el mismo prompt tras agotar el límite suele repetir la estrategia. La siguiente ejecución debe recibir el bloqueo o una tarea más pequeña.
• Presupuesto compartido: una corrección local y una migración transversal no compran el mismo trabajo con seis turnos.
• Logs sensibles: elimina secretos y datos personales antes de almacenar prompts, salidas de herramientas o diffs.
• Gate controlado por el agente: vuelve a ejecutar la validación desde el wrapper o CI. No aceptes únicamente el resumen final.

Registra también la versión de la CLI y la configuración del agente. GitHub incluye la versión conocida de Copilot CLI en sus informes por usuario, lo que ayuda a distinguir una regresión del flujo de un cambio de cliente.

Cuándo no aplica este presupuesto

No todo trabajo de desarrollo debe convertirse en una ejecución cerrada. Este enfoque pierde utilidad cuando no puedes expresar todavía qué significa terminar.

Un plan de suscripción con coste fijo tampoco elimina el problema. Aunque una ejecución adicional no produzca un cargo directo, puede consumir tiempo de CI, atención de revisión o capacidad limitada de uso. El objetivo del contrato es controlar trabajo sin evidencia, no perseguir el token más barato.

Preguntas frecuentes

¿Un turno equivale a una llamada al modelo?

No en todas las herramientas. Usa la definición y telemetría de tu CLI; el presupuesto necesita una unidad que el runtime pueda detener, no una equivalencia universal.

¿Debo subir el límite cuando el agente falla por un turno?

Solo si el diff y la salida del gate muestran progreso concreto. Si repite búsquedas, comandos o errores, divide la tarea o corrige el contexto antes de conceder más intentos.

¿El límite de turnos sustituye al control de coste?

No. Los turnos acotan autonomía; los tokens, precios y cuotas controlan consumo. Necesitas ambos controles cuando pagas por uso, pero cada uno responde a un fallo diferente.

El criterio que conviene recordar

Un coding agent merece más autonomía cuando puedes verificar su salida, no cuando todavía queda presupuesto. Define el gate, asigna turnos y tiempo según el riesgo, y convierte el agotamiento en una escalada con evidencias. Si no sabes cómo demostrar que la tarea ha terminado, aún no está lista para ejecutarse sin supervisión.